@codewizard-dt/bootstrap 2.10.0 → 2.11.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 (68) hide show
  1. package/README.md +20 -7
  2. package/lib/README.md +1 -1
  3. package/lib/hooks/README.md +13 -12
  4. package/lib/prompts/setup-strict-typechecks.md +1 -1
  5. package/lib/scripts/README.md +3 -1
  6. package/lib/scripts/build-mcp-guide.sh +1 -1
  7. package/lib/scripts/install-global.sh +7 -1
  8. package/lib/scripts/install-mcps.sh +176 -13
  9. package/lib/scripts/lib.sh +16 -0
  10. package/lib/scripts/merge-settings-deny.js +124 -0
  11. package/lib/scripts/setup-project.sh +16 -3
  12. package/lib/scripts/templates/guides/stubs/playwright.md +1 -1
  13. package/lib/scripts/templates/settings-deny.json +38 -0
  14. package/lib/skills/anti-slop/SKILL.md +1 -1
  15. package/lib/skills/bug-close/SKILL.md +1 -1
  16. package/lib/skills/bug-file/SKILL.md +1 -1
  17. package/lib/skills/bug-triage/SKILL.md +1 -1
  18. package/lib/skills/company-align/SKILL.md +1 -1
  19. package/lib/skills/debug-logs/SKILL.md +1 -1
  20. package/lib/skills/decision-create/SKILL.md +2 -2
  21. package/lib/skills/decision-finalize/SKILL.md +1 -1
  22. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  23. package/lib/skills/demo/SKILL.md +1 -1
  24. package/lib/skills/elevator-pitch/SKILL.md +1 -1
  25. package/lib/skills/eval-create/SKILL.md +1 -1
  26. package/lib/skills/eval-gap/SKILL.md +1 -1
  27. package/lib/skills/eval-run/SKILL.md +1 -1
  28. package/lib/skills/extract-feature/SKILL.md +1 -1
  29. package/lib/skills/flashcard/SKILL.md +1 -1
  30. package/lib/skills/frontend-taste/SKILL.md +1 -1
  31. package/lib/skills/gap-assess/SKILL.md +1 -1
  32. package/lib/skills/lint/SKILL.md +1 -1
  33. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  34. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  35. package/lib/skills/now/SKILL.md +1 -1
  36. package/lib/skills/port-feature/SKILL.md +1 -1
  37. package/lib/skills/power-mode/SKILL.md +1 -1
  38. package/lib/skills/project-readme/SKILL.md +1 -1
  39. package/lib/skills/req-compile/SKILL.md +1 -1
  40. package/lib/skills/req-create/SKILL.md +1 -1
  41. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  42. package/lib/skills/req-finalize/SKILL.md +1 -1
  43. package/lib/skills/req-update/SKILL.md +1 -1
  44. package/lib/skills/research/SKILL.md +1 -1
  45. package/lib/skills/research-company/SKILL.md +2 -2
  46. package/lib/skills/roadmap-create/SKILL.md +1 -1
  47. package/lib/skills/security-audit/SKILL.md +1 -1
  48. package/lib/skills/simplify/SKILL.md +1 -1
  49. package/lib/skills/tackle/SKILL.md +1 -1
  50. package/lib/skills/task-add/SKILL.md +1 -1
  51. package/lib/skills/task-audit/SKILL.md +1 -1
  52. package/lib/skills/task-update/SKILL.md +1 -1
  53. package/lib/skills/uat-auto/SKILL.md +1 -1
  54. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  55. package/lib/skills/uat-generate/SKILL.md +1 -1
  56. package/lib/skills/uat-walk/SKILL.md +1 -1
  57. package/lib/skills/update-docs/SKILL.md +1 -1
  58. package/lib/skills/wiki-archive/SKILL.md +1 -1
  59. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  60. package/lib/skills/wiki-lint/SKILL.md +1 -1
  61. package/lib/skills/wiki-query/SKILL.md +1 -1
  62. package/lib/skills/wiki-rotate-log/SKILL.md +1 -1
  63. package/lib/skills/wiki-tidy/SKILL.md +1 -1
  64. package/package.json +1 -1
  65. package/raw/research/brave-mcp-single-docker-container/index.md +94 -0
  66. package/raw/research/brave-mcp-single-docker-container/sources.md +70 -0
  67. package/raw/research/mcp-one-process-per-user/index.md +75 -0
  68. package/raw/research/mcp-one-process-per-user/sources.md +66 -0
package/README.md CHANGED
@@ -41,7 +41,7 @@ At a glance, the package entry point selects a script, scripts copy or generate
41
41
  #### MCP Installer
42
42
 
43
43
  - **Responsibility:** Registers Serena, Brave Search, Context7, and Playwright MCP servers with the correct user or project scope.
44
- - **Tech:** Bash, `claude mcp add`, `uvx`, `npx`
44
+ - **Tech:** Bash, `claude mcp add`, `uvx`, `npx`, Docker (shared `brave-search-mcp` container), launchd (macOS Playwright LaunchAgent)
45
45
  - **Inputs:** `--interactive`, `--project-dir`, `BRAVE_API_KEY`, optional `CONTEXT7_API_KEY`, and scope choices from interactive prompts.
46
46
  - **Outputs:** User-scope MCP registrations for shared tools and project-scope `.mcp.json` registration for Serena when selected.
47
47
  - **Depends on:** Claude Code CLI, uv/uvx, npm package execution
@@ -129,6 +129,7 @@ flowchart LR
129
129
  subgraph Global ["Global Claude Code State"]
130
130
  GSKILLS["~/.claude/skills/"]
131
131
  GHOOKS["~/.claude/hooks/"]
132
+ GSETTINGS["~/.claude/settings.json<br/>permissions.deny"]
132
133
  GMCP["User MCPs<br/>Brave, Context7, Playwright"]
133
134
  end
134
135
 
@@ -143,7 +144,9 @@ flowchart LR
143
144
  subgraph External ["External Tools"]
144
145
  CLAUDE["Claude Code CLI"]
145
146
  UVX["uvx<br/>Serena"]
146
- NPX["npx<br/>MCP packages"]
147
+ DOCKER["Docker<br/>brave-search-mcp container<br/>http :8941"]
148
+ LAUNCHD["launchd<br/>playwright-mcp LaunchAgent<br/>http :8931 (macOS)"]
149
+ NPX["npx<br/>Playwright MCP (non-macOS stdio)"]
147
150
  GHA["GitHub Actions"]
148
151
  NPM["npm Registry"]
149
152
  end
@@ -160,12 +163,15 @@ flowchart LR
160
163
  SETUP -->|runs| SERENA
161
164
  INSTALL -->|rsync| SKILLS
162
165
  INSTALL -->|rsync| HOOKS
166
+ INSTALL -->|merge deny list| GSETTINGS
163
167
  SKILLS -->|copy| GSKILLS
164
168
  HOOKS -->|copy| GHOOKS
165
169
  MCPS -->|claude mcp add| GMCP
166
170
  MCPS -->|project scope| MCP_JSON
167
171
  MCPS -->|launches| UVX
168
- MCPS -->|launches| NPX
172
+ MCPS -->|docker run| DOCKER
173
+ MCPS -->|bootstraps plist| LAUNCHD
174
+ MCPS -->|non-macOS| NPX
169
175
  WIKI -->|copy-once + refresh| TEMPLATES
170
176
  WIKI -->|writes| WIKI_DIR
171
177
  GUIDE -->|assemble selected sections| STUBS
@@ -196,11 +202,14 @@ sequenceDiagram
196
202
  Dev->>CLI: npx @codewizard-dt/bootstrap setup
197
203
  CLI->>Setup: execFileSync(setup-project.sh ".")
198
204
  Setup->>MCP: install-mcps.sh --interactive --project-dir <project>
199
- MCP->>Claude: claude mcp add selected servers
205
+ MCP-->>MCP: docker run brave-search-mcp (http :8941, API key baked in)
206
+ MCP-->>MCP: bootstrap playwright launchd agent (http :8931, macOS)
207
+ MCP->>Claude: claude mcp add selected servers (http URLs for brave/playwright)
200
208
  MCP-->>Project: .mcp.json for Serena when selected
201
209
  Setup->>Global: install-global.sh --skip-mcps
202
210
  Global-->>Global: rsync skills to ~/.claude/skills/
203
211
  Global-->>Global: rsync hooks to ~/.claude/hooks/
212
+ Global-->>Global: merge canonical deny list into ~/.claude/settings.json
204
213
  Setup->>Wiki: sync-wiki-scaffold.sh <project>
205
214
  Wiki-->>Project: raw/, wiki/, CLAUDE.md snippets, .docs/guides/
206
215
  Setup->>Guide: build-mcp-guide.sh <project> <installed-mcps>
@@ -323,7 +332,9 @@ No environment variables are required to build or publish this package from a lo
323
332
 
324
333
  | Variable | Required | Example | Description |
325
334
  |---|---|---|---|
326
- | `BRAVE_API_KEY` | yes for non-interactive Brave MCP install | `BSA...` | Secret passed to the Brave Search MCP server; prompted interactively if absent. |
335
+ | `BRAVE_API_KEY` | yes for non-interactive Brave MCP install | `BSA...` | Secret baked into the `brave-search-mcp` Docker container's environment at creation (it stays out of `~/.claude.json`); prompted interactively if absent. To rotate: `docker rm -f brave-search-mcp`, then re-run `bootstrap update` with the new key. |
336
+ | `BRAVE_MCP_PORT` | no — defaults to `8941` | `8941` | Host port for the shared Brave Search MCP Docker container (mapped to the container's fixed port `8941`); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
337
+ | `PLAYWRIGHT_MCP_PORT` | no — defaults to `8931` | `8931` | Port the shared Playwright MCP launchd agent listens on (macOS); the registered endpoint is `http://127.0.0.1:<port>/mcp`. |
327
338
  | `CONTEXT7_API_KEY` | optional for Context7 MCP install | `ctx_...` | Optional secret sent as a Context7 MCP HTTP header; Context7 can be installed without it. |
328
339
  | `GITHUB_TOKEN` | yes in GitHub Actions | `${{ secrets.GITHUB_TOKEN }}` | GitHub-provided token used by Gitleaks and GHCR login in workflows. |
329
340
  | `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` | yes in workflows | `true` | Plain workflow config forcing JavaScript actions to run on Node 24. |
@@ -465,8 +476,10 @@ Useful first places to inspect:
465
476
  - **`command not found: bootstrap`:** The package binary is not on PATH; run through `npx @codewizard-dt/bootstrap <command>` or use `node bin/cli.js <command>` locally.
466
477
  - **`claude: command not found`:** Claude Code is missing; install it with `npm install -g @anthropic-ai/claude-code` before running setup, deploy scaffolding, migration, or typecheck setup.
467
478
  - **`uv: command not found`:** Serena setup cannot launch; install uv so `uvx` is available, then rerun setup.
468
- - **Brave MCP install prompts for an API key:** Set `BRAVE_API_KEY` before non-interactive installs or enter it when prompted by `install-mcps.sh`.
479
+ - **Brave MCP install prompts for an API key:** Set `BRAVE_API_KEY` before non-interactive installs or enter it when prompted by `install-mcps.sh`. The key is baked into the `brave-search-mcp` container at creation, so a re-run never re-prompts while the container exists; to change the key, `docker rm -f brave-search-mcp` and re-run `bootstrap update`. Brave install also requires Docker to be running — if it is not, the script skips brave-search until the next `bootstrap update`.
480
+ - **`brave-search endpoint not answering`:** The shared container should be serving `http://127.0.0.1:8941/mcp` (host port overridable via `BRAVE_MCP_PORT`). Check `docker logs brave-search-mcp` and confirm Docker Desktop is running; enable Docker Desktop's "Start when you sign in" so the container comes back after reboots.
481
+ - **`playwright endpoint not answering` (macOS):** The launchd agent `com.bootstrap-claude.playwright-mcp` should be serving `http://127.0.0.1:8931/mcp` (overridable via `PLAYWRIGHT_MCP_PORT`). Inspect it with `launchctl print gui/$(id -u)/com.bootstrap-claude.playwright-mcp` and check `~/Library/Logs/playwright-mcp.log`. Over SSH there is no GUI session for the agent to bootstrap into — log into the Mac GUI once, then re-run `bootstrap update`.
469
482
  - **Context7 installs without authenticated access:** Set `CONTEXT7_API_KEY` if authenticated Context7 access is required; otherwise the script can register Context7 without the header.
470
- - **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`.
483
+ - **Hooks copy but do not run:** `install-global.sh` copies scripts to `~/.claude/hooks/`, but hook registration in `~/.claude/settings.json` is a separate manual step documented in `lib/hooks/README.md`. The `permissions.deny` list is the exception: `install-global.sh` merges the canonical deny list from `lib/scripts/templates/settings-deny.json` into `~/.claude/settings.json` automatically (additive-only — your own entries are never removed or reordered). Deleting a canonical entry locally means it gets re-added on the next `install`/`setup`/`update` run; that re-convergence is the point of a canonical list.
471
484
  - **Manual build workflow skips:** `.github/workflows/build.yml` intentionally skips the build job unless a root-level `Dockerfile` exists.
472
485
  - **npm package points at unexpected repository metadata:** Check `package.json` `repository`, `homepage`, and `bugs` fields before publishing; they are independent of the local git remote.
package/lib/README.md CHANGED
@@ -12,7 +12,7 @@ lib/
12
12
 
13
13
  | Folder | What it is | Installed to |
14
14
  |--------|-----------|---------------|
15
- | [`hooks/`](hooks/README.md) | Enforcement scripts that block unsafe or non-Serena tool calls, even under `--dangerously-skip-permissions` | `~/.claude/hooks/` (copied by `install-global.sh`; registration in `~/.claude/settings.json` is manual — see `hooks/README.md`) |
15
+ | [`hooks/`](hooks/README.md) | Enforcement scripts that block unsafe or non-Serena tool calls, even under `--dangerously-skip-permissions` | `~/.claude/hooks/` (copied by `install-global.sh`; registration in `~/.claude/settings.json` is manual — see `hooks/README.md` — though the `permissions.deny` list is merged automatically) |
16
16
  | [`scripts/`](scripts/README.md) | Bash scripts that back every `bootstrap` CLI command, plus shared helpers and copy-once templates | Run in place from the installed npm package; write into the target project and `~/.claude/` |
17
17
  | [`prompts/`](prompts/README.md) | Prompt templates for the setup steps that are too context-sensitive for static file copies (CI scaffolding, wiki migration, strict typechecks) | Read by scripts in `lib/scripts/` at runtime; never installed anywhere themselves |
18
18
  | [`skills/`](skills/README.md) | One directory per skill, each holding a `SKILL.md` — the wiki-ops, requirement/decision/task/UAT/bug lifecycle, research, and utility skills | `~/.claude/skills/` (copied verbatim by `install-global.sh`) |
@@ -299,18 +299,19 @@ for why both events are wired. If your Claude Code build does not support
299
299
  `PostToolUseFailure`, that block is simply ignored and the `PostToolUse` error
300
300
  path still catches failures.
301
301
 
302
- Recommended companion `deny` entries (belt-and-suspenders for normal modes):
302
+ The companion `deny` entries (belt-and-suspenders for normal modes) no longer
303
+ need manual wiring: the full canonical deny list lives in
304
+ [`lib/scripts/templates/settings-deny.json`](../scripts/templates/settings-deny.json)
305
+ and is merged into `~/.claude/settings.json` automatically by
306
+ `install-global.sh` (so by `bootstrap install`, `setup`, and `update`). The
307
+ merge is additive-only — your own entries are never removed or reordered.
303
308
 
304
- ```json
305
- {
306
- "permissions": {
307
- "deny": [
308
- "Bash(git stash:*)",
309
- "Bash(git restore:*)",
310
- "Bash(git checkout:*)"
311
- ]
312
- }
313
- }
314
- ```
309
+ Two documented caveats on those deny rules:
310
+
311
+ - Deny rules are **not enforced** in `bypassPermissions` mode — that is exactly
312
+ why these hooks exist (see above). The deny list covers normal modes.
313
+ - `Bash(git push --force *)` / `Bash(git push -f *)` are prefix matches, so a
314
+ command like `git push origin main --force` slips past them — partial
315
+ protection only.
315
316
 
316
317
  Hooks load at session start, so restart any running session after wiring.
@@ -93,7 +93,7 @@ Write ~/.claude/skills/typecheck/SKILL.md with this exact content (do not alter
93
93
  ---
94
94
  name: typecheck
95
95
  description: Run typecheck, fix the first error, repeat until clean
96
- model: claude-sonnet-4-6
96
+ model: claude-sonnet-5
97
97
  disable-model-invocation: false
98
98
  user-invocable: true
99
99
  ---
@@ -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 sync, `.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 + `.docs/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-*`). Accepts `--skip-mcps` when the caller already handled MCP install interactively. |
13
+ | `install-global.sh` | `install` | Installs/updates MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`), and merges the canonical Bash deny list into `~/.claude/settings.json` via `merge-settings-deny.js`. 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 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`, 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`. |
@@ -26,6 +26,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
26
26
  | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh` | Assembles `.docs/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
28
  | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Copies the packaged `.gitignore` template into the target project if none exists; otherwise merges in only the missing lines, leaving the project's existing `.gitignore` content untouched. |
29
+ | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical Bash deny list (`templates/settings-deny.json`) into `~/.claude/settings.json` `permissions.deny`. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
29
30
 
30
31
  ## Standalone infra scripts (not wired to the CLI)
31
32
 
@@ -47,3 +48,4 @@ Static and semi-static assets copied or read by the scripts above — never exec
47
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). |
48
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). |
49
50
  | `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
51
+ | `templates/settings-deny.json` | `merge-settings-deny.js` | The canonical `permissions.deny` list (bare JSON array of rule strings): destructive disk/system commands, `sudo`, permission footguns, and git working-tree/history protections. Audited against the Claude Code permission-rule docs; merged additively into `~/.claude/settings.json` on every `install`/`setup`/`update`. |
@@ -97,7 +97,7 @@ EOF
97
97
  echo "| Library docs | Context7 | \`WebSearch\` / \`WebFetch\` |"
98
98
  fi
99
99
  if has_mcp "brave-search"; then
100
- echo "| General research | Brave Search (sequential, 1/sec) | Parallel searches |"
100
+ echo "| General research | Brave Search (parallel, up to 50/sec) | \`WebSearch\` |"
101
101
  fi
102
102
  if has_mcp "playwright"; then
103
103
  echo "| Browser interaction | Playwright | \`WebFetch\` for rendered content |"
@@ -75,4 +75,10 @@ if [ ${#ORPHAN_FOUND[@]} -gt 0 ]; then
75
75
  fi
76
76
  fi
77
77
 
78
- echo "Global setup complete (MCPs + skills)."
78
+ # 4. Merge the canonical Bash deny list into ~/.claude/settings.json
79
+ echo ""
80
+ echo "Merging permissions deny list (~/.claude/settings.json)..."
81
+ node "$SCRIPT_DIR/merge-settings-deny.js"
82
+ echo ""
83
+
84
+ echo "Global setup complete (MCPs + hooks + skills + deny list)."
@@ -24,6 +24,17 @@ while [[ $# -gt 0 ]]; do
24
24
  esac
25
25
  done
26
26
 
27
+ # Single source of truth for the local MCP ports/URLs (env-overridable):
28
+ # registration, upgrade checks, and epilogue text all derive from these.
29
+ BRAVE_MCP_PORT="${BRAVE_MCP_PORT:-8941}"
30
+ PLAYWRIGHT_MCP_PORT="${PLAYWRIGHT_MCP_PORT:-8931}"
31
+ BRAVE_MCP_URL="http://127.0.0.1:${BRAVE_MCP_PORT}/mcp"
32
+ # playwright MUST be addressed as `localhost`, not 127.0.0.1: @playwright/mcp's
33
+ # DNS-rebinding guard only accepts the `localhost` Host header (even when the
34
+ # server is started with --host 127.0.0.1) — 127.0.0.1 URLs get 403 "Access is
35
+ # only allowed at localhost:<port>". Found by TASK-025 runtime UAT.
36
+ PLAYWRIGHT_MCP_URL="http://localhost:${PLAYWRIGHT_MCP_PORT}/mcp"
37
+
27
38
  # mcp_installed, serena_installed, prompt_yn, prompt_scope live in lib.sh.
28
39
 
29
40
  # mcp_add_scoped <scope> <claude-mcp-add-args...>
@@ -39,16 +50,26 @@ mcp_add_scoped() {
39
50
  fi
40
51
  }
41
52
 
42
- # register_optional_mcp <name> <interactive-prompt> <adder-fn>
53
+ # register_optional_mcp <name> <interactive-prompt> <adder-fn> [expected]
43
54
  # Common wrapper for the optional MCPs (brave-search / context7 / playwright):
44
55
  # skip if already installed; in interactive mode gate on a y/n prompt and ask
45
56
  # for scope; otherwise install non-interactively at user scope. <adder-fn>
46
57
  # performs the actual `claude mcp add` (including any API-key prompting) and
47
58
  # receives the resolved scope ("user" | "project") as its only argument.
59
+ # Optional [expected]: a string the existing registration must contain (checked
60
+ # via mcp_matches, lib.sh). If installed but not matching, the stale
61
+ # registration is removed and the adder re-run directly at user scope (upgrade
62
+ # path — the server was already wanted, so no interactive gating is re-applied).
48
63
  register_optional_mcp() {
49
- local name="$1" prompt="$2" adder="$3" scope
64
+ local name="$1" prompt="$2" adder="$3" expected="${4:-}" scope
50
65
  if mcp_installed "$name"; then
51
- echo " $name: already installed, skipping."
66
+ if [ -z "$expected" ] || mcp_matches "$name" "$expected"; then
67
+ echo " $name: already installed, skipping."
68
+ return 0
69
+ fi
70
+ echo " $name: upgrading registration (stdio → shared http)."
71
+ claude mcp remove "$name" -s user 2>/dev/null || true
72
+ "$adder" user
52
73
  return 0
53
74
  fi
54
75
  if [ "$INTERACTIVE" = true ]; then
@@ -68,22 +89,45 @@ register_optional_mcp() {
68
89
  # interactive vs non-interactive key-prompting behaviour of the original blocks.
69
90
  _add_brave() {
70
91
  if [ "$INTERACTIVE" = true ]; then
71
- read -r -p " BRAVE_API_KEY (get one at https://brave.com/search/api/): " BRAVE_API_KEY
92
+ read -r -p " BRAVE_API_KEY (get one at https://brave.com/search/api/): " BRAVE_API_KEY || true
72
93
  elif [ -z "${BRAVE_API_KEY:-}" ]; then
73
94
  echo -n " Enter your Brave Search API key (get one at https://brave.com/search/api/): "
74
- read -r BRAVE_API_KEY
95
+ read -r BRAVE_API_KEY || true
75
96
  fi
76
- mcp_add_scoped "$1" brave-search \
77
- --env "BRAVE_API_KEY=${BRAVE_API_KEY}" \
78
- -- npx -y @modelcontextprotocol/server-brave-search
97
+ if [ -z "${BRAVE_API_KEY:-}" ]; then
98
+ echo " No BRAVE_API_KEY provided — skipping brave-search registration."
99
+ return 0
100
+ fi
101
+ docker info >/dev/null 2>&1 || { echo " Docker not running — skipping brave-search (re-run 'bootstrap update' with Docker up)"; return 0; }
102
+ # Migrate any pre-existing container based on its entrypoint:
103
+ case "$(docker inspect -f '{{.Path}}' brave-search-mcp 2>/dev/null)" in
104
+ sleep) docker rm -f brave-search-mcp >/dev/null ;; # old exec-wrapper container
105
+ node) docker start brave-search-mcp >/dev/null 2>&1 || true ;; # already converted
106
+ esac
107
+ if ! docker inspect brave-search-mcp >/dev/null 2>&1; then
108
+ # Key is baked into the container env (visible via `docker inspect` to
109
+ # docker-socket holders; accepted trade-off — it stays out of ~/.claude.json).
110
+ # Rotation: `docker rm -f brave-search-mcp` + re-run `bootstrap update`.
111
+ # Prefix assignment is required: value-less `-e BRAVE_API_KEY` only forwards
112
+ # EXPORTED vars, and `read` doesn't export.
113
+ BRAVE_API_KEY="$BRAVE_API_KEY" docker run -d --restart unless-stopped \
114
+ --name brave-search-mcp -e BRAVE_API_KEY \
115
+ -p "127.0.0.1:${BRAVE_MCP_PORT}:8941" docker.io/mcp/brave-search \
116
+ --transport http --host 0.0.0.0 --port 8941
117
+ fi
118
+ # Always user scope: a project-scoped brave entry would shadow the global one.
119
+ mcp_add_scoped user brave-search --transport http "$BRAVE_MCP_URL"
120
+ wait_http_up "$BRAVE_MCP_URL" && echo " brave-search: listening on $BRAVE_MCP_URL" \
121
+ || echo " WARNING: brave-search endpoint not answering — check 'docker logs brave-search-mcp'"
122
+ echo " Tip: enable Docker Desktop's \"Start when you sign in\" so brave-search comes back after reboots."
79
123
  }
80
124
 
81
125
  _add_context7() {
82
126
  if [ "$INTERACTIVE" = true ]; then
83
- read -r -p " CONTEXT7_API_KEY (optional — press Enter to skip; get one at https://context7.com/dashboard): " CONTEXT7_API_KEY
127
+ read -r -p " CONTEXT7_API_KEY (optional — press Enter to skip; get one at https://context7.com/dashboard): " CONTEXT7_API_KEY || true
84
128
  elif [ -z "${CONTEXT7_API_KEY:-}" ]; then
85
129
  echo -n " Enter your Context7 API key (optional — press Enter to skip, get one at https://context7.com/dashboard): "
86
- read -r CONTEXT7_API_KEY
130
+ read -r CONTEXT7_API_KEY || true
87
131
  fi
88
132
  if [ -n "${CONTEXT7_API_KEY:-}" ]; then
89
133
  mcp_add_scoped "$1" --transport http \
@@ -95,8 +139,111 @@ _add_context7() {
95
139
  fi
96
140
  }
97
141
 
142
+ # _playwright_bootstrap_agent <gui-domain> <plist>
143
+ # launchctl-bootstraps the playwright LaunchAgent into the user's GUI domain.
144
+ # Returns 0 on success; 2 when there is no GUI session to bootstrap into
145
+ # ("Bootstrap failed: 5" — typical over SSH; hint printed here); 1 on any
146
+ # other failure (warning printed, caller falls through to diagnostics).
147
+ _playwright_bootstrap_agent() {
148
+ local out
149
+ if out="$(launchctl bootstrap "$1" "$2" 2>&1)"; then
150
+ return 0
151
+ fi
152
+ case "$out" in
153
+ *"Bootstrap failed: 5"*)
154
+ echo " playwright: no GUI session (running over SSH?) — log into the Mac GUI once, then re-run 'bootstrap update'."
155
+ return 2 ;;
156
+ esac
157
+ echo " WARNING: launchctl bootstrap failed: $out"
158
+ return 1
159
+ }
160
+
98
161
  _add_playwright() {
99
- mcp_add_scoped "$1" playwright -- npx @playwright/mcp@latest
162
+ if [ "$(uname -s)" != "Darwin" ]; then
163
+ # Non-macOS: per-session stdio server (shared-server wiring is macOS-only for now).
164
+ mcp_add_scoped "$1" playwright -- npx @playwright/mcp@latest
165
+ return 0
166
+ fi
167
+ # macOS: one shared HTTP server per machine, run as a launchd LaunchAgent in
168
+ # the Aqua (GUI) session so headed browsers keep working. NEVER npx under
169
+ # launchd: agents get PATH=/usr/bin:/bin:/usr/sbin:/sbin, so neither `npx`
170
+ # nor its `#!/usr/bin/env node` shebang resolve — and @latest would force an
171
+ # npm-registry round-trip on every start (offline crash-loop). Instead:
172
+ # install the package globally now and have launchd invoke node directly on
173
+ # the package's cli entry.
174
+ local label plist tmp node_bin pw_cli uid log_file rc
175
+ npm install -g @playwright/mcp@latest \
176
+ || { echo " ERROR: 'npm install -g @playwright/mcp' failed — fix npm, then re-run 'bootstrap update'."; return 1; }
177
+ node_bin="$(command -v node || true)"
178
+ [ -n "$node_bin" ] \
179
+ || { echo " ERROR: node not found on PATH — install Node.js, then re-run 'bootstrap update'."; return 1; }
180
+ pw_cli="$(npm root -g)/@playwright/mcp/cli.js"
181
+ [ -f "$pw_cli" ] \
182
+ || { echo " ERROR: $pw_cli missing — global @playwright/mcp install did not produce a cli entry."; return 1; }
183
+ label="com.bootstrap-claude.playwright-mcp"
184
+ plist="$HOME/Library/LaunchAgents/${label}.plist"
185
+ log_file="$HOME/Library/Logs/playwright-mcp.log"
186
+ uid="$(id -u)"
187
+ mkdir -p "$HOME/Library/LaunchAgents" "$HOME/Library/Logs"
188
+ tmp="$(mktemp)"
189
+ cat > "$tmp" <<PLIST
190
+ <?xml version="1.0" encoding="UTF-8"?>
191
+ <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
192
+ <plist version="1.0">
193
+ <dict>
194
+ <key>Label</key>
195
+ <string>${label}</string>
196
+ <key>ProgramArguments</key>
197
+ <array>
198
+ <string>${node_bin}</string>
199
+ <string>${pw_cli}</string>
200
+ <string>--port</string>
201
+ <string>${PLAYWRIGHT_MCP_PORT}</string>
202
+ <string>--host</string>
203
+ <string>127.0.0.1</string>
204
+ </array>
205
+ <key>RunAtLoad</key>
206
+ <true/>
207
+ <key>KeepAlive</key>
208
+ <dict>
209
+ <key>SuccessfulExit</key>
210
+ <false/>
211
+ </dict>
212
+ <key>ThrottleInterval</key>
213
+ <integer>30</integer>
214
+ <key>LimitLoadToSessionType</key>
215
+ <string>Aqua</string>
216
+ <key>StandardOutPath</key>
217
+ <string>${log_file}</string>
218
+ <key>StandardErrorPath</key>
219
+ <string>${log_file}</string>
220
+ <key>WorkingDirectory</key>
221
+ <string>${HOME}</string>
222
+ </dict>
223
+ </plist>
224
+ PLIST
225
+ rc=0
226
+ if ! cmp -s "$tmp" "$plist"; then
227
+ # New or changed plist: install it and (re)start the agent.
228
+ mv "$tmp" "$plist"
229
+ launchctl bootout "gui/${uid}/${label}" 2>/dev/null || true
230
+ _playwright_bootstrap_agent "gui/${uid}" "$plist" || rc=$?
231
+ else
232
+ rm -f "$tmp"
233
+ if ! launchctl print "gui/${uid}/${label}" >/dev/null 2>&1; then
234
+ # Plist unchanged but agent not loaded (fresh login session / prior bootout).
235
+ _playwright_bootstrap_agent "gui/${uid}" "$plist" || rc=$?
236
+ fi
237
+ fi
238
+ if [ "$rc" -eq 2 ]; then
239
+ return 0
240
+ fi
241
+ # Always user scope: a project-scoped playwright entry would shadow the global one.
242
+ mcp_add_scoped user playwright --transport http "$PLAYWRIGHT_MCP_URL"
243
+ wait_http_up "$PLAYWRIGHT_MCP_URL" && echo " playwright: listening on $PLAYWRIGHT_MCP_URL" \
244
+ || { echo " WARNING: playwright endpoint not answering — diagnostics:"; \
245
+ launchctl print "gui/${uid}/${label}" 2>/dev/null || true; \
246
+ echo " Log: ${log_file}"; }
100
247
  }
101
248
 
102
249
  # ---------------------------------------------------------------------------
@@ -122,10 +269,26 @@ fi
122
269
  # Optional MCPs (near-identical wrappers — see register_optional_mcp above)
123
270
  # ---------------------------------------------------------------------------
124
271
  register_optional_mcp brave-search \
125
- "Install Brave Search MCP (web research, requires API key)? [y/N]: " _add_brave
272
+ "Install Brave Search MCP globally (web research, requires API key + Docker)? [y/N]: " _add_brave "$BRAVE_MCP_URL"
126
273
 
127
274
  register_optional_mcp context7 \
128
275
  "Install Context7 MCP (library documentation lookups)? [y/N]: " _add_context7
129
276
 
277
+ # Shared-http upgrade detection is darwin-only: on Linux the stdio entry is the
278
+ # desired end state, so pass an empty expected arg there (empty = never upgrade).
279
+ playwright_expected=""
280
+ if [ "$(uname -s)" = "Darwin" ]; then
281
+ playwright_expected="$PLAYWRIGHT_MCP_URL"
282
+ fi
130
283
  register_optional_mcp playwright \
131
- "Install Playwright MCP (browser automation & UI testing)? [y/N]: " _add_playwright
284
+ "Install Playwright MCP (browser automation & UI testing)? [y/N]: " _add_playwright "$playwright_expected"
285
+
286
+ # Darwin only: a project-scoped playwright entry in the project's .mcp.json
287
+ # shadows the user-scope shared HTTP server. Detection mirrors serena_installed
288
+ # (lib.sh). Hint only — never edit a project's .mcp.json.
289
+ if [ "$(uname -s)" = "Darwin" ] && [ -n "$PROJECT_DIR" ] \
290
+ && [ -f "$PROJECT_DIR/.mcp.json" ] \
291
+ && grep -q '"playwright"' "$PROJECT_DIR/.mcp.json" 2>/dev/null; then
292
+ echo " WARNING: playwright is also registered in $PROJECT_DIR/.mcp.json (project scope) — it shadows the user-scope shared HTTP server."
293
+ echo " Remove it with: cd \"$PROJECT_DIR\" && claude mcp remove playwright -s project"
294
+ fi
@@ -39,6 +39,22 @@ mcp_installed() {
39
39
  claude mcp get "$1" &>/dev/null
40
40
  }
41
41
 
42
+ # ---------------------------------------------------------------------------
43
+ # mcp_matches <name> <expected>
44
+ #
45
+ # Fixed-string match against `claude mcp get` output; used to distinguish
46
+ # "installed with expected shape" from "installed but stale (needs upgrade)".
47
+ # ---------------------------------------------------------------------------
48
+ mcp_matches() { claude mcp get "$1" 2>/dev/null | grep -qF "$2"; }
49
+
50
+ # ---------------------------------------------------------------------------
51
+ # wait_http_up <url> [attempts]
52
+ #
53
+ # Any HTTP status proves the listener is up — streamable-HTTP servers 4xx
54
+ # plain GETs, so `curl -f` would false-negative.
55
+ # ---------------------------------------------------------------------------
56
+ wait_http_up() { local i code; for i in $(seq 1 "${2:-10}"); do code="$(curl -s -o /dev/null -m 2 -w '%{http_code}' "$1" 2>/dev/null || true)"; [ -n "$code" ] && [ "$code" != "000" ] && return 0; sleep 1; done; return 1; }
57
+
42
58
  # ---------------------------------------------------------------------------
43
59
  # serena_installed <project_dir>
44
60
  #
@@ -0,0 +1,124 @@
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.
4
+ //
5
+ // Additive union only: canonical entries missing from the user's list are
6
+ // appended; user entries are never removed, reordered, or deduplicated, and
7
+ // every other settings key passes through untouched.
8
+ //
9
+ // Always exits 0 — the caller (install-global.sh) runs under `set -euo
10
+ // pipefail` and a settings merge must never abort an install. Any state we
11
+ // don't understand (unparseable JSON, unexpected shapes) warns and skips,
12
+ // leaving the target file untouched.
13
+ //
14
+ // Usage: merge-settings-deny.js [--target <path>] [--source <path>]
15
+ // --target/--source exist as test seams; the install flow passes no args.
16
+
17
+ 'use strict';
18
+
19
+ const fs = require('fs');
20
+ const os = require('os');
21
+ const path = require('path');
22
+
23
+ function parseArgs(argv) {
24
+ const opts = {
25
+ target: path.join(os.homedir(), '.claude', 'settings.json'),
26
+ source: path.join(__dirname, 'templates', 'settings-deny.json'),
27
+ };
28
+ for (let i = 0; i < argv.length; i++) {
29
+ if (argv[i] === '--target' && argv[i + 1]) opts.target = argv[++i];
30
+ else if (argv[i] === '--source' && argv[i + 1]) opts.source = argv[++i];
31
+ }
32
+ return opts;
33
+ }
34
+
35
+ function warnSkip(message) {
36
+ console.error(`Warning: ${message} — skipping deny-list merge`);
37
+ process.exit(0);
38
+ }
39
+
40
+ function isPlainObject(value) {
41
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
42
+ }
43
+
44
+ const { target, source } = parseArgs(process.argv.slice(2));
45
+
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})`);
51
+ }
52
+ if (!Array.isArray(canonical) || !canonical.every((e) => typeof e === 'string')) {
53
+ warnSkip(`settings-deny template is not an array of strings (${source})`);
54
+ }
55
+
56
+ let raw = null;
57
+ if (fs.existsSync(target)) {
58
+ try {
59
+ raw = fs.readFileSync(target, 'utf8');
60
+ } catch (err) {
61
+ warnSkip(`could not read ${target}`);
62
+ }
63
+ }
64
+
65
+ let settings = {};
66
+ if (raw !== null) {
67
+ try {
68
+ settings = JSON.parse(raw);
69
+ } catch (err) {
70
+ warnSkip(`could not parse ${target} (file untouched)`);
71
+ }
72
+ if (!isPlainObject(settings)) {
73
+ warnSkip(`${target} is not a JSON object (file untouched)`);
74
+ }
75
+ }
76
+
77
+ if ('permissions' in settings && !isPlainObject(settings.permissions)) {
78
+ warnSkip(`${target}: "permissions" is not an object (file untouched)`);
79
+ }
80
+ const permissions = settings.permissions || (settings.permissions = {});
81
+ if ('deny' in permissions && !Array.isArray(permissions.deny)) {
82
+ warnSkip(`${target}: "permissions.deny" is not an array (file untouched)`);
83
+ }
84
+ const deny = permissions.deny || (permissions.deny = []);
85
+
86
+ const existing = new Set(deny);
87
+ let added = 0;
88
+ for (const entry of canonical) {
89
+ if (!existing.has(entry)) {
90
+ deny.push(entry);
91
+ console.log(` + ${entry}`);
92
+ added++;
93
+ }
94
+ }
95
+
96
+ if (added === 0 && raw !== null) {
97
+ console.log('settings.json: deny list already up to date');
98
+ process.exit(0);
99
+ }
100
+
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
+ }
119
+
120
+ if (raw === null) {
121
+ console.log(`settings.json: created with ${added} deny entries`);
122
+ } else {
123
+ console.log(`settings.json: ${added} deny entr${added === 1 ? 'y' : 'ies'} merged`);
124
+ }
@@ -47,9 +47,22 @@ echo "API keys (if you skipped any during setup):"
47
47
  echo " brave-search BRAVE_API_KEY https://brave.com/search/api/"
48
48
  echo " context7 CONTEXT7_API_KEY (optional) https://context7.com/dashboard"
49
49
  echo ""
50
- echo "To add a key later:"
51
- echo " claude mcp remove brave-search -s user"
52
- echo " claude mcp add --scope user brave-search --env BRAVE_API_KEY=<key> -- npx -y @modelcontextprotocol/server-brave-search"
50
+ echo "To add a Brave key later:"
51
+ echo " export BRAVE_API_KEY=<key>, then re-run 'npx @codewizard-dt/bootstrap update' (starts the container and registers the server), or manually:"
52
+ echo " BRAVE_API_KEY=<key> docker run -d --restart unless-stopped --name brave-search-mcp -e BRAVE_API_KEY -p \"127.0.0.1:8941:8941\" docker.io/mcp/brave-search --transport http --host 0.0.0.0 --port 8941"
53
+ echo " claude mcp add --scope user --transport http brave-search http://127.0.0.1:8941/mcp"
53
54
  echo ""
55
+ echo "To rotate the Brave API key:"
56
+ echo " docker rm -f brave-search-mcp, then re-run 'npx @codewizard-dt/bootstrap update' (recreates the container with the new key)"
57
+ echo ""
58
+ echo "To update the brave-search server image:"
59
+ echo " docker rm -f brave-search-mcp && docker pull docker.io/mcp/brave-search (then re-run 'bootstrap update' to recreate the container)"
60
+ echo ""
61
+ echo "To restart or update the playwright server (macOS launchd agent):"
62
+ echo " npm i -g @playwright/mcp@latest && launchctl kickstart -k gui/\$(id -u)/com.bootstrap-claude.playwright-mcp"
63
+ echo ""
64
+ echo "Ports: brave-search 8941, playwright 8931 — override via BRAVE_MCP_PORT / PLAYWRIGHT_MCP_PORT env vars set before running setup/update"
65
+ echo ""
66
+ echo "To add a Context7 key later:"
54
67
  echo " claude mcp remove context7 -s user"
55
68
  echo " claude mcp add --scope user --transport http --header \"CONTEXT7_API_KEY: <key>\" context7 https://mcp.context7.com/mcp"
@@ -17,7 +17,7 @@
17
17
 
18
18
  ### Workflow
19
19
 
20
- 1. **No explicit launch step** — the browser starts automatically on the first tool call.
20
+ 1. **No explicit launch step** — the browser starts automatically on the first tool call. On macOS the browser server is a shared, launchd-managed HTTP service (one per machine); each session still gets an isolated browser context.
21
21
  2. **Accessibility-tree first** — always call `browser_snapshot` to get the current page structure and element `ref` IDs before interacting. Pass the `ref` to `browser_click`, `browser_type`, etc.
22
22
  3. Use `browser_take_screenshot` for visual verification after navigation or interaction.
23
23