@codewizard-dt/bootstrap 2.14.0 → 2.17.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 (40) hide show
  1. package/lib/hooks/README.md +639 -142
  2. package/lib/hooks/absolute-path-guard.js +142 -0
  3. package/lib/hooks/claude-settings-guard.js +200 -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 +73 -8
  11. package/lib/scripts/build-mcp-guide.sh +9 -1
  12. package/lib/scripts/install-global.sh +62 -11
  13. package/lib/scripts/install-mcps.sh +140 -36
  14. package/lib/scripts/lib.sh +24 -15
  15. package/lib/scripts/merge-gitignore.sh +221 -33
  16. package/lib/scripts/merge-settings-deny.js +112 -39
  17. package/lib/scripts/merge-settings-hooks.js +374 -0
  18. package/lib/scripts/templates/file-suggestion.sh +142 -0
  19. package/lib/scripts/templates/gitignore +8 -0
  20. package/lib/scripts/templates/guides/stubs/playwright.md +2 -0
  21. package/lib/scripts/templates/settings-deny.json +81 -1
  22. package/lib/scripts/templates/settings-hooks.json +151 -0
  23. package/lib/skills/debug-logs/SKILL.md +1 -1
  24. package/lib/skills/git-commit/SKILL.md +8 -0
  25. package/package.json +5 -2
  26. package/raw/research/brave-mcp-single-docker-container/index.md +0 -94
  27. package/raw/research/brave-mcp-single-docker-container/sources.md +0 -70
  28. package/raw/research/dark-mode-theme/index.md +0 -85
  29. package/raw/research/dark-mode-theme/sources.md +0 -49
  30. package/raw/research/mcp-add-scope-writes/index.md +0 -46
  31. package/raw/research/mcp-add-scope-writes/sources.md +0 -38
  32. package/raw/research/mcp-one-process-per-user/index.md +0 -75
  33. package/raw/research/mcp-one-process-per-user/sources.md +0 -66
  34. package/raw/research/mcp-scope-conflict-handling/index.md +0 -61
  35. package/raw/research/mcp-scope-conflict-handling/sources.md +0 -32
  36. package/raw/research/serena-mcp-disconnect/index.md +0 -81
  37. package/raw/research/serena-mcp-disconnect/sources.md +0 -87
  38. package/raw/research/wiki-tooling-improvements/index.md +0 -126
  39. package/raw/research/wiki-tooling-improvements/sources.md +0 -73
  40. package/raw/software-factory-case-study.pdf +0 -0
@@ -34,10 +34,12 @@ BRAVE_MCP_URL="http://127.0.0.1:${BRAVE_MCP_PORT}/mcp"
34
34
  # server is started with --host 127.0.0.1) — 127.0.0.1 URLs get 403 "Access is
35
35
  # only allowed at localhost:<port>". Found by TASK-025 runtime UAT.
36
36
  PLAYWRIGHT_MCP_URL="http://localhost:${PLAYWRIGHT_MCP_PORT}/mcp"
37
- # The bootstrap-managed server registers under its own name so it can coexist
38
- # with a project-scoped `playwright` entry in a team's committed .mcp.json —
39
- # we never edit that file; a distinct name avoids [Conflicting scopes] entirely.
40
- PLAYWRIGHT_MCP_NAME="${PLAYWRIGHT_MCP_NAME:-playwright-shared}"
37
+ # Default server name. When a project already ships its own `playwright`
38
+ # registration, the interactive conflict flow (see _install_playwright_flow)
39
+ # may register ours under the alternate name below instead — a team's
40
+ # committed .mcp.json is never edited.
41
+ PLAYWRIGHT_MCP_NAME="${PLAYWRIGHT_MCP_NAME:-playwright}"
42
+ PLAYWRIGHT_MCP_ALT_NAME="${PLAYWRIGHT_MCP_ALT_NAME:-playwright-shared}"
41
43
 
42
44
  # mcp_installed, serena_installed, prompt_yn, prompt_scope live in lib.sh.
43
45
 
@@ -178,9 +180,11 @@ _playwright_bootstrap_agent() {
178
180
  }
179
181
 
180
182
  _add_playwright() {
183
+ # $1 = scope, $2 = server name (defaults to the canonical name)
184
+ local reg_name="${2:-$PLAYWRIGHT_MCP_NAME}"
181
185
  if [ "$(uname -s)" != "Darwin" ]; then
182
186
  # Non-macOS: per-session stdio server (shared-server wiring is macOS-only for now).
183
- mcp_add_scoped "$1" "$PLAYWRIGHT_MCP_NAME" -- npx @playwright/mcp@latest
187
+ mcp_add_scoped "$1" "$reg_name" -- npx @playwright/mcp@latest
184
188
  return 0
185
189
  fi
186
190
  # macOS: one shared HTTP server per machine, run as a launchd LaunchAgent in
@@ -257,11 +261,10 @@ PLIST
257
261
  if [ "$rc" -eq 2 ]; then
258
262
  return 0
259
263
  fi
260
- # Always user scope, under our own name — coexists with any project-scoped
261
- # `playwright` a team ships in .mcp.json.
262
- mcp_add_scoped user "$PLAYWRIGHT_MCP_NAME" --transport http "$PLAYWRIGHT_MCP_URL"
263
- wait_http_up "$PLAYWRIGHT_MCP_URL" && echo " $PLAYWRIGHT_MCP_NAME: listening on $PLAYWRIGHT_MCP_URL" \
264
- || { echo " WARNING: $PLAYWRIGHT_MCP_NAME endpoint not answering — diagnostics:"; \
264
+ # Always user scope for the shared HTTP server.
265
+ mcp_add_scoped user "$reg_name" --transport http "$PLAYWRIGHT_MCP_URL"
266
+ wait_http_up "$PLAYWRIGHT_MCP_URL" && echo " $reg_name: listening on $PLAYWRIGHT_MCP_URL" \
267
+ || { echo " WARNING: $reg_name endpoint not answering — diagnostics:"; \
265
268
  launchctl print "gui/${uid}/${label}" 2>/dev/null || true; \
266
269
  echo " Log: ${log_file}"; }
267
270
  }
@@ -310,30 +313,131 @@ register_optional_mcp brave-search \
310
313
  register_optional_mcp context7 \
311
314
  "Install Context7 MCP (library documentation lookups)? [y/N]: " _add_context7
312
315
 
313
- # Migrate the legacy bootstrap-managed `playwright` USER-scope entry to the new
314
- # name. Only shapes bootstrap itself created are touched (the shared-http URL
315
- # or the old stdio `npx @playwright/mcp` form), and only at user scope — a
316
- # project-scoped `playwright` is repository config and coexists with ours by
317
- # name. Detection reads ~/.claude.json top-level mcpServers directly because
318
- # `claude mcp get playwright` resolves to the project entry when one exists.
319
- if node -e '
320
- const p = (require(require("os").homedir() + "/.claude.json").mcpServers || {}).playwright;
321
- if (!p) process.exit(1);
322
- const j = JSON.stringify(p);
323
- process.exit(j.includes(process.argv[1]) || j.includes("@playwright/mcp") ? 0 : 1);
324
- ' "$PLAYWRIGHT_MCP_URL" 2>/dev/null; then
325
- echo " playwright: migrating legacy bootstrap user-scope entry to '$PLAYWRIGHT_MCP_NAME'."
326
- claude mcp remove playwright -s user 2>/dev/null || true
327
- fi
316
+ # _disable_project_playwright_locally
317
+ # Rejects the project's .mcp.json `playwright` on THIS machine only, via
318
+ # disabledMcpjsonServers in $PROJECT_DIR/.claude/settings.local.json — the
319
+ # team's .mcp.json is never touched. Idempotent; warns + skips on unparseable
320
+ # or unexpected file shapes (same fail-safe posture as merge-settings-deny.js).
321
+ _disable_project_playwright_locally() {
322
+ node -e '
323
+ const fs = require("fs"), path = require("path");
324
+ const file = path.join(process.argv[1], ".claude", "settings.local.json");
325
+ let s = {};
326
+ if (fs.existsSync(file)) {
327
+ try { s = JSON.parse(fs.readFileSync(file, "utf8")); } catch (e) {
328
+ console.error(" WARNING: could not parse " + file + " — skipping local disable."); process.exit(0);
329
+ }
330
+ if (typeof s !== "object" || s === null || Array.isArray(s)) {
331
+ console.error(" WARNING: " + file + " is not a JSON object — skipping local disable."); process.exit(0);
332
+ }
333
+ }
334
+ if ("disabledMcpjsonServers" in s && !Array.isArray(s.disabledMcpjsonServers)) {
335
+ console.error(" WARNING: disabledMcpjsonServers is not an array — skipping local disable."); process.exit(0);
336
+ }
337
+ const list = s.disabledMcpjsonServers || (s.disabledMcpjsonServers = []);
338
+ if (!list.includes("playwright")) list.push("playwright");
339
+ fs.mkdirSync(path.dirname(file), { recursive: true });
340
+ const tmp = file + ".tmp-" + process.pid;
341
+ fs.writeFileSync(tmp, JSON.stringify(s, null, 2) + "\n");
342
+ fs.renameSync(tmp, file);
343
+ console.log(" playwright: project entry disabled on this machine (.claude/settings.local.json disabledMcpjsonServers).");
344
+ ' "$PROJECT_DIR" || true
345
+ }
328
346
 
329
- # Shared-http upgrade detection is darwin-only: on Linux the stdio entry is the
330
- # desired end state, so pass an empty expected arg there (empty = never upgrade).
331
- # The scope prompt is skipped on darwin (the shared server is user-scope only).
332
- playwright_expected=""
333
- playwright_fixed_scope=""
334
- if [ "$(uname -s)" = "Darwin" ]; then
335
- playwright_expected="$PLAYWRIGHT_MCP_URL"
336
- playwright_fixed_scope="user"
337
- fi
338
- register_optional_mcp "$PLAYWRIGHT_MCP_NAME" \
339
- "Install Playwright MCP (browser automation & UI testing)? [y/N]: " _add_playwright "$playwright_expected" "$playwright_fixed_scope"
347
+ # _install_playwright_flow
348
+ # Dedicated install/conflict logic for playwright (the generic wrapper cannot
349
+ # express this). Two variables decide the path: WHERE an existing `playwright`
350
+ # registration lives (user / project / local), and — for project scope —
351
+ # whether .mcp.json is CHECKED IN (git-tracked ⇒ team-owned, never modified).
352
+ _install_playwright_flow() {
353
+ local pw_scope choice expected=""
354
+ [ "$(uname -s)" = "Darwin" ] && expected="$PLAYWRIGHT_MCP_URL"
355
+
356
+ # Rename-back: a user-scope `playwright-shared` pointing at our URL is the
357
+ # never-published 2.11.3 naming — fold it back into the canonical name when
358
+ # no conflicting `playwright` blocks that (the conflict branches below keep
359
+ # it as-is, since there it IS the desired registration).
360
+ if ! mcp_installed playwright && mcp_installed "$PLAYWRIGHT_MCP_ALT_NAME" \
361
+ && mcp_matches "$PLAYWRIGHT_MCP_ALT_NAME" "$PLAYWRIGHT_MCP_URL"; then
362
+ echo " playwright: reverting '$PLAYWRIGHT_MCP_ALT_NAME' back to the canonical name 'playwright'."
363
+ claude mcp remove "$PLAYWRIGHT_MCP_ALT_NAME" -s user 2>/dev/null || true
364
+ _add_playwright user "$PLAYWRIGHT_MCP_NAME"
365
+ return 0
366
+ fi
367
+
368
+ if ! mcp_installed playwright; then
369
+ # Fresh install (same gating as register_optional_mcp).
370
+ if [ "$INTERACTIVE" = true ]; then
371
+ if prompt_yn "Install Playwright MCP (browser automation & UI testing)? [y/N]: "; then
372
+ _add_playwright user "$PLAYWRIGHT_MCP_NAME"
373
+ echo " playwright MCP installed."
374
+ fi
375
+ else
376
+ echo " Installing playwright MCP..."
377
+ _add_playwright user "$PLAYWRIGHT_MCP_NAME"
378
+ echo " playwright MCP installed."
379
+ fi
380
+ return 0
381
+ fi
382
+
383
+ pw_scope="$(mcp_scope_of playwright)"
384
+
385
+ if [ "$pw_scope" = "user" ]; then
386
+ if [ -z "$expected" ] || mcp_matches playwright "$expected"; then
387
+ echo " playwright: already installed, skipping."
388
+ else
389
+ echo " playwright: upgrading registration (stdio → shared http)."
390
+ claude mcp remove playwright -s user 2>/dev/null || true
391
+ _add_playwright user "$PLAYWRIGHT_MCP_NAME"
392
+ fi
393
+ # Cleanup a leftover alternate-name duplicate of ours at user scope.
394
+ if mcp_installed "$PLAYWRIGHT_MCP_ALT_NAME" && mcp_matches "$PLAYWRIGHT_MCP_ALT_NAME" "$PLAYWRIGHT_MCP_URL"; then
395
+ echo " playwright: removing duplicate '$PLAYWRIGHT_MCP_ALT_NAME' user-scope entry."
396
+ claude mcp remove "$PLAYWRIGHT_MCP_ALT_NAME" -s user 2>/dev/null || true
397
+ fi
398
+ return 0
399
+ fi
400
+
401
+ # Conflict: playwright registered at project/local scope (or undetectable).
402
+ if [ "$INTERACTIVE" != true ] || [ ! -t 0 ] || [ -z "$PROJECT_DIR" ] || [ "$pw_scope" = "unknown" ]; then
403
+ echo " playwright: an existing ${pw_scope}-scope registration was found — leaving everything untouched."
404
+ echo " Resolve interactively: run 'npx @codewizard-dt/bootstrap update' in a terminal to choose how to proceed."
405
+ return 0
406
+ fi
407
+
408
+ if [ "$pw_scope" = "project" ] \
409
+ && git -C "$PROJECT_DIR" ls-files --error-unmatch .mcp.json >/dev/null 2>&1; then
410
+ # Team-owned: .mcp.json is checked into the repo. NEVER modified.
411
+ echo " playwright: this project's committed .mcp.json registers its own playwright server."
412
+ echo " [1] Register the bootstrap shared server as '$PLAYWRIGHT_MCP_ALT_NAME' and disable the project one on this machine only"
413
+ echo " [2] Register '$PLAYWRIGHT_MCP_ALT_NAME' alongside it (both active — browser tools will appear twice)"
414
+ echo " [3] Don't touch anything (default)"
415
+ read -r -p " How should we proceed? [1/2/3]: " choice || choice=3
416
+ case "$choice" in
417
+ 1)
418
+ _add_playwright user "$PLAYWRIGHT_MCP_ALT_NAME"
419
+ _disable_project_playwright_locally
420
+ ;;
421
+ 2)
422
+ _add_playwright user "$PLAYWRIGHT_MCP_ALT_NAME"
423
+ ;;
424
+ *)
425
+ echo " playwright: left untouched."
426
+ ;;
427
+ esac
428
+ return 0
429
+ fi
430
+
431
+ # Machine-local registration: untracked .mcp.json (project scope) or the
432
+ # ~/.claude.json project entry (local scope). Safe to modify with consent.
433
+ echo " playwright: an existing ${pw_scope}-scope registration was found (machine-local, not checked in)."
434
+ if prompt_yn " Replace it with the bootstrap shared server (removes the ${pw_scope}-scope entry)? [y/N] (no = keep it and register ours as '$PLAYWRIGHT_MCP_ALT_NAME'): "; then
435
+ ( cd "$PROJECT_DIR" && claude mcp remove playwright -s "$pw_scope" ) || true
436
+ _add_playwright user "$PLAYWRIGHT_MCP_NAME"
437
+ else
438
+ _add_playwright user "$PLAYWRIGHT_MCP_ALT_NAME"
439
+ echo " playwright: existing entry kept; bootstrap server registered as '$PLAYWRIGHT_MCP_ALT_NAME'."
440
+ fi
441
+ }
442
+
443
+ _install_playwright_flow
@@ -59,11 +59,14 @@ mcp_matches() { claude mcp get "$1" 2>/dev/null | grep -qF "$2"; }
59
59
  mcp_scope_of() {
60
60
  local line
61
61
  line="$(claude mcp get "$1" 2>/dev/null | grep -m1 'Scope:')" || { echo unknown; return 0; }
62
+ # Match the scope word immediately after "Scope: " — descriptive parentheticals
63
+ # like "Local config (private to you in this project)" contain other scope
64
+ # words, so loose substring matching misclassifies.
62
65
  case "$line" in
63
- *User*) echo user ;;
64
- *[Pp]roject*) echo project ;;
65
- *[Ll]ocal*) echo local ;;
66
- *) echo unknown ;;
66
+ *"Scope: User"*|*"Scope: user"*) echo user ;;
67
+ *"Scope: Project"*|*"Scope: project"*) echo project ;;
68
+ *"Scope: Local"*|*"Scope: local"*) echo local ;;
69
+ *) echo unknown ;;
67
70
  esac
68
71
  }
69
72
 
@@ -107,8 +110,9 @@ detect_installed_mcps() {
107
110
  result="${result:+$result }$mcp"
108
111
  fi
109
112
  done
110
- # The bootstrap-managed playwright server registers as "playwright-shared" so
111
- # it can coexist with a project-scoped "playwright"; either name enables the
113
+ # The bootstrap-managed playwright server is normally named "playwright";
114
+ # "playwright-shared" is the conflict-resolution alternate (used when a
115
+ # project ships its own playwright entry). Either name enables the
112
116
  # playwright guide section (guide key stays "playwright").
113
117
  if mcp_installed "playwright-shared" || mcp_installed "playwright"; then
114
118
  result="${result:+$result }playwright"
@@ -120,25 +124,30 @@ detect_installed_mcps() {
120
124
  # run_project_sync <project_dir> <script_dir>
121
125
  #
122
126
  # The shared setup/update sequence run identically by setup-project.sh and
123
- # update-project.sh: install MCPs interactively, install skills+hooks globally,
124
- # sync the wiki scaffold (tiered guide delivery — --interactive enables the
125
- # optional-guide prompts), merge the .gitignore, build the MCP-tools guide for
126
- # the detected MCPs, then bootstrap Serena's project.yml. Prints the same
127
- # section headers and blank-line separators the two scripts printed inline.
127
+ # update-project.sh: install skills+hooks globally first (offline-safe, via
128
+ # install-global.sh --skip-mcps), then attempt the interactive MCP install
129
+ # (guarded — a failure only warns and continues, it does not abort the rest
130
+ # of the sync), sync the wiki scaffold (tiered guide delivery — --interactive
131
+ # enables the optional-guide prompts), merge the .gitignore, build the
132
+ # MCP-tools guide for the detected MCPs, then bootstrap Serena's project.yml.
133
+ # Prints the same section headers and blank-line separators the two scripts
134
+ # printed inline.
128
135
  # ---------------------------------------------------------------------------
129
136
  run_project_sync() {
130
137
  local project_dir script_dir installed_mcps
131
138
  project_dir="$1"
132
139
  script_dir="$2"
133
140
 
134
- echo "Checking MCP servers..."
135
- "$script_dir/install-mcps.sh" --interactive --project-dir "$project_dir"
136
- echo ""
137
-
138
141
  echo "Installing skills and hooks globally..."
139
142
  "$script_dir/install-global.sh" --skip-mcps
140
143
  echo ""
141
144
 
145
+ echo "Checking MCP servers..."
146
+ if ! "$script_dir/install-mcps.sh" --interactive --project-dir "$project_dir"; then
147
+ echo "Warning: MCP install failed — continuing with wiki sync; re-run update to retry MCPs." >&2
148
+ fi
149
+ echo ""
150
+
142
151
  echo "Syncing wiki scaffold..."
143
152
  "$script_dir/sync-wiki-scaffold.sh" --interactive "$project_dir"
144
153
  "$script_dir/merge-gitignore.sh" --interactive "$project_dir"
@@ -8,14 +8,12 @@ TEMPLATE_GITIGNORE="$SCRIPT_DIR/templates/gitignore"
8
8
 
9
9
  # merge-gitignore.sh [--interactive] <path-to-project>
10
10
  #
11
- # The template is split into titled sections (delimited by `# ---` banner
12
- # comments). Per section:
13
- # - already represented in the target (any of its entries present, exact
14
- # line match) => merge the section's missing lines silently (sticky opt-in)
15
- # - otherwise, --interactive => prompt "Add .gitignore section '<title>'?"
16
- # (default no); non-interactive => skip silently
17
- # A missing .gitignore is copied wholesale in non-interactive mode; in
18
- # interactive mode the same per-section prompts build it from scratch.
11
+ # NOTHING is ever added to a project's .gitignore without asking. The template
12
+ # is split into titled sections (delimited by `# ---` banner comments); every
13
+ # section with missing lines is offered by title ("Add/update .gitignore
14
+ # section '<title>' (N new line(s))? [y/N]") — even sections already partially
15
+ # present. Sections with nothing new are skipped silently. Non-interactive
16
+ # runs (or no tty) change nothing at all, including when no .gitignore exists.
19
17
 
20
18
  INTERACTIVE=false
21
19
  POSITIONAL=()
@@ -37,11 +35,10 @@ PROJECT_DIR="$(resolve_project_dir "$1")" || exit 1
37
35
 
38
36
  TARGET="$PROJECT_DIR/.gitignore"
39
37
 
40
- # No target + non-interactive (or no tty to prompt on) → copy wholesale, so
41
- # headless setup keeps full coverage instead of creating an empty file.
42
- if [ ! -f "$TARGET" ] && { [ "$INTERACTIVE" = false ] || [ ! -t 0 ]; }; then
43
- cp "$TEMPLATE_GITIGNORE" "$TARGET"
44
- echo ".gitignore: copied to $PROJECT_DIR"
38
+ # Interactive-only: without a tty there is nobody to ask, and we never add
39
+ # .gitignore entries without asking.
40
+ if [ "$INTERACTIVE" = false ] || [ ! -t 0 ]; then
41
+ echo ".gitignore: skipped (interactive only — run 'npx @codewizard-dt/bootstrap update' in a terminal to be offered the sections)."
45
42
  exit 0
46
43
  fi
47
44
 
@@ -68,26 +65,41 @@ SECTION_COUNT=$(awk -v dir="$WORK_DIR" '
68
65
  END { print n }
69
66
  ' "$TEMPLATE_GITIGNORE")
70
67
 
71
- [ -f "$TARGET" ] || : > "$TARGET"
72
-
73
- # Snapshot existing lines for exact-match lookups during the merge loops
68
+ # Snapshot existing lines for exact-match lookups during the merge loops.
69
+ # The target itself is NOT pre-created — it comes into existence only when a
70
+ # section is accepted (merge_section appends).
74
71
  EXISTING="$WORK_DIR/existing"
75
- cp "$TARGET" "$EXISTING"
72
+ if [ -f "$TARGET" ]; then cp "$TARGET" "$EXISTING"; else : > "$EXISTING"; fi
76
73
 
77
- # section_represented <section-file>: any non-comment entry already in target?
78
- section_represented() {
79
- local line trimmed
74
+ # section_missing_count <section-file>: how many non-comment entries are not
75
+ # yet in the target (exact line match)?
76
+ section_missing_count() {
77
+ local line trimmed n=0
80
78
  while IFS= read -r line || [ -n "$line" ]; do
81
79
  trimmed="${line#"${line%%[![:space:]]*}"}"
82
80
  [ -z "$trimmed" ] && continue
83
81
  case "$trimmed" in \#*) continue ;; esac
84
- if grep -qFx -- "$line" "$EXISTING"; then return 0; fi
82
+ grep -qFx -- "$line" "$EXISTING" || n=$((n + 1))
85
83
  done < "$1"
86
- return 1
84
+ echo "$n"
87
85
  }
88
86
 
89
87
  added=0
90
88
 
89
+ # section_missing_lines <section-file>: print the entries that would be added,
90
+ # one per line, indented. Same selection logic as section_missing_count — a
91
+ # count alone ("3 new line(s)?") asks the user to consent to something they
92
+ # cannot see, so the prompt shows exactly what it will write.
93
+ section_missing_lines() {
94
+ local line trimmed
95
+ while IFS= read -r line || [ -n "$line" ]; do
96
+ trimmed="${line#"${line%%[![:space:]]*}"}"
97
+ [ -z "$trimmed" ] && continue
98
+ case "$trimmed" in \#*) continue ;; esac
99
+ grep -qFx -- "$line" "$EXISTING" || printf ' %s\n' "$line"
100
+ done < "$1"
101
+ }
102
+
91
103
  # merge_section <section-file>: append the section's missing lines, keeping
92
104
  # comment/blank lines buffered so headers only land when new entries follow.
93
105
  merge_section() {
@@ -116,23 +128,199 @@ merge_section() {
116
128
  done < "$1"
117
129
  }
118
130
 
131
+ # Tally before asking anything: the opening question should state the real
132
+ # scope, and a project with nothing to offer must not be asked at all.
133
+ total_missing=0
134
+ sections_offered=0
119
135
  i=1
120
136
  while [ "$i" -le "$SECTION_COUNT" ]; do
121
- SEC="$WORK_DIR/sec.$i"
122
- TITLE="section $i"
123
- [ -f "$WORK_DIR/title.$i" ] && TITLE="$(cat "$WORK_DIR/title.$i")"
124
- if section_represented "$SEC"; then
125
- merge_section "$SEC"
126
- elif [ "$INTERACTIVE" = true ] && prompt_yn " Add .gitignore section '$TITLE'? [y/N]: "; then
127
- merge_section "$SEC"
128
- else
129
- echo " .gitignore section '$TITLE': skipped (opt in via 'npx @codewizard-dt/bootstrap update')."
137
+ n="$(section_missing_count "$WORK_DIR/sec.$i")"
138
+ if [ "$n" -gt 0 ]; then
139
+ total_missing=$((total_missing + n))
140
+ sections_offered=$((sections_offered + 1))
130
141
  fi
131
142
  i=$((i + 1))
132
143
  done
133
144
 
134
- if [ "$added" -eq 0 ]; then
135
- echo ".gitignore: already up to date in $PROJECT_DIR"
145
+ # One gate for the whole .gitignore pass, so a user who does not want their
146
+ # .gitignore touched answers once instead of once per section. This covers the
147
+ # section loop ONLY — the .git/info/exclude block below is a different mechanism
148
+ # (machine-local, never committed) and keeps its own prompt, so declining here
149
+ # still lets the sentinel repair run.
150
+ review_sections=0
151
+ if [ "$total_missing" -eq 0 ]; then
152
+ echo ".gitignore: already has everything the template offers in $PROJECT_DIR"
153
+ elif prompt_yn " Review .gitignore updates? ($total_missing line(s) across $sections_offered section(s)) [y/N]: "; then
154
+ review_sections=1
136
155
  else
156
+ echo ".gitignore: skipped entirely — no sections offered."
157
+ fi
158
+
159
+ if [ "$review_sections" -eq 1 ]; then
160
+ i=1
161
+ while [ "$i" -le "$SECTION_COUNT" ]; do
162
+ SEC="$WORK_DIR/sec.$i"
163
+ TITLE="section $i"
164
+ [ -f "$WORK_DIR/title.$i" ] && TITLE="$(cat "$WORK_DIR/title.$i")"
165
+ missing="$(section_missing_count "$SEC")"
166
+ if [ "$missing" -gt 0 ]; then
167
+ # Show the actual lines before asking. Comment/blank lines are omitted:
168
+ # they are only written as headers when a real entry follows, so listing
169
+ # them would misrepresent what the "y" adds.
170
+ echo " .gitignore section '$TITLE' would add $missing line(s):"
171
+ section_missing_lines "$SEC"
172
+ if prompt_yn " Add these to .gitignore? [y/N]: "; then
173
+ merge_section "$SEC"
174
+ else
175
+ echo " .gitignore section '$TITLE': skipped."
176
+ fi
177
+ fi
178
+ i=$((i + 1))
179
+ done
180
+ fi
181
+
182
+ # Only summarise when the section pass actually ran; the gate's own message
183
+ # already said what happened otherwise, and a second "no changes made" line
184
+ # reads as if something was attempted.
185
+ if [ "$added" -gt 0 ]; then
137
186
  echo ".gitignore: $added line(s) merged into $PROJECT_DIR"
187
+ elif [ "$review_sections" -eq 1 ]; then
188
+ echo ".gitignore: no changes made in $PROJECT_DIR"
189
+ fi
190
+
191
+ # Machine-local git exclusion for bootstrap agent state. These dirs must NEVER
192
+ # go into .gitignore: Serena (ignore_all_files_in_gitignore: true) and Claude
193
+ # Code's Grep mirror .gitignore and would go blind on the wiki. .git/info/exclude
194
+ # has identical semantics for git, is never committed (a per-machine choice,
195
+ # offered per-machine), and is invisible to Serena — its GitignoreParser reads
196
+ # only files named ".gitignore", so the dirs stay navigable. It is NOT invisible
197
+ # to every tool: ripgrep-class walkers and Claude Code's @ file picker do honor
198
+ # info/exclude. That is why install-global.sh installs ~/.claude/file-suggestion.sh
199
+ # and registers it as the fileSuggestion picker — it re-includes exactly the paths
200
+ # listed under the sentinel written below.
201
+ GIT_EXCLUDE="$PROJECT_DIR/.git/info/exclude"
202
+ EXCLUDE_SENTINEL="# bootstrap wiki & agent state (machine-local)"
203
+
204
+ # Canonical form is what file-suggestion.sh can actually parse: the sentinel
205
+ # line, immediately followed by .serena/, raw/, wiki/ in that order, each of the
206
+ # four appearing exactly once, and the block terminated by a "#" comment or EOF.
207
+ # A path sitting ABOVE the sentinel is still excluded by git but invisible to the
208
+ # picker, so appending only the absent paths is not enough — we normalize.
209
+ exclude_is_canonical() {
210
+ [ -f "$1" ] || return 1
211
+ awk -v sentinel="$EXCLUDE_SENTINEL" '
212
+ { line[NR] = $0 }
213
+ $0 == sentinel { sent++; at = NR }
214
+ $0 == ".serena/" { a++ }
215
+ $0 == "raw/" { b++ }
216
+ $0 == "wiki/" { c++ }
217
+ END {
218
+ if (sent != 1 || a != 1 || b != 1 || c != 1) exit 1
219
+ if (line[at + 1] != ".serena/" || line[at + 2] != "raw/" || line[at + 3] != "wiki/") exit 1
220
+ if (at + 3 < NR && line[at + 4] !~ /^[[:space:]]*#/) exit 1
221
+ exit 0
222
+ }
223
+ ' "$1"
224
+ }
225
+
226
+ # A user's own entry sitting INSIDE the sentinel block. Normalizing re-appends
227
+ # our block at the bottom and leaves such an entry above it: git still excludes
228
+ # it, but the picker stops re-including it, so say so rather than change the
229
+ # user's view of their own file silently.
230
+ exclude_stranded() {
231
+ [ -f "$1" ] || return 0
232
+ awk -v sentinel="$EXCLUDE_SENTINEL" '
233
+ $0 == sentinel { in_block = 1; next }
234
+ in_block && /^[[:space:]]*#/ { in_block = 0 }
235
+ in_block && $0 !~ /^[[:space:]]*$/ \
236
+ && $0 != ".serena/" && $0 != "raw/" && $0 != "wiki/" { print " " $0 }
237
+ ' "$1"
238
+ }
239
+
240
+ # Scrub every occurrence of the sentinel and of the three exact whole-line paths
241
+ # from anywhere in the file, then re-append the canonical block at the bottom.
242
+ # Every other line survives verbatim and in its original order (this file may
243
+ # hold the user's own exclusions); only a blank run the scrub itself created is
244
+ # collapsed, and the result ends with exactly one newline.
245
+ exclude_normalize() {
246
+ local file="$1" src="$1" tmp mode=""
247
+ [ -f "$src" ] || src=/dev/null
248
+ if [ -f "$file" ]; then
249
+ mode=$(stat -f '%Lp' "$file" 2>/dev/null || stat -c '%a' "$file" 2>/dev/null || true)
250
+ fi
251
+ mkdir -p "$(dirname "$file")" || return 1
252
+ tmp=$(mktemp "$(dirname "$file")/.bootstrap-exclude.XXXXXX") || return 1
253
+ awk -v sentinel="$EXCLUDE_SENTINEL" '
254
+ BEGIN { n = 0; prev_blank = 1; dropped = 0 }
255
+ $0 == sentinel || $0 == ".serena/" || $0 == "raw/" || $0 == "wiki/" { dropped = 1; next }
256
+ {
257
+ if ($0 ~ /^[[:space:]]*$/) {
258
+ if (prev_blank && dropped) next
259
+ prev_blank = 1
260
+ } else {
261
+ prev_blank = 0
262
+ }
263
+ keep[++n] = $0
264
+ dropped = 0
265
+ }
266
+ END {
267
+ while (n > 1 && keep[n] ~ /^[[:space:]]*$/ && keep[n - 1] ~ /^[[:space:]]*$/) n--
268
+ if (n == 1 && keep[1] ~ /^[[:space:]]*$/) n = 0
269
+ for (i = 1; i <= n; i++) print keep[i]
270
+ print sentinel
271
+ print ".serena/"
272
+ print "raw/"
273
+ print "wiki/"
274
+ }
275
+ ' "$src" > "$tmp" || { rm -f "$tmp"; return 1; }
276
+ mv -f "$tmp" "$file" || { rm -f "$tmp"; return 1; }
277
+ if [ -n "$mode" ]; then chmod "$mode" "$file" 2>/dev/null || true; fi
278
+ return 0
279
+ }
280
+
281
+ # Normalize and report. Never fatal: this runs under `set -euo pipefail` from
282
+ # run_project_sync and must not abort the user's setup.
283
+ exclude_apply() {
284
+ local stranded
285
+ stranded=$(exclude_stranded "$GIT_EXCLUDE")
286
+ if ! exclude_normalize "$GIT_EXCLUDE"; then
287
+ echo " Warning: could not update $GIT_EXCLUDE — left unchanged."
288
+ return 1
289
+ fi
290
+ if [ -n "$stranded" ]; then
291
+ echo " Note: these entries were inside the bootstrap block and now sit above it."
292
+ echo " git still excludes them; @-autocomplete will no longer list them:"
293
+ printf '%s\n' "$stranded"
294
+ fi
295
+ return 0
296
+ }
297
+
298
+ if [ -d "$PROJECT_DIR/.git" ]; then
299
+ exclude_missing=0
300
+ exclude_added=""
301
+ for p in ".serena/" "raw/" "wiki/"; do
302
+ if [ -f "$GIT_EXCLUDE" ] && grep -qFx -- "$p" "$GIT_EXCLUDE"; then
303
+ continue
304
+ fi
305
+ exclude_missing=$((exclude_missing + 1))
306
+ exclude_added="${exclude_added} + ${p} (.git/info/exclude)"$'\n'
307
+ done
308
+
309
+ if exclude_is_canonical "$GIT_EXCLUDE"; then
310
+ : # already canonical — leave the file byte-identical
311
+ elif [ "$exclude_missing" -gt 0 ]; then
312
+ # Accepting newly hides paths from git, so this stays a consent prompt.
313
+ if prompt_yn " Keep .serena/, raw/, wiki/ out of git on THIS machine (.git/info/exclude — not shared with the team; visible to Serena; @-autocomplete restored via the installed fileSuggestion script)? [y/N]: "; then
314
+ if exclude_apply; then
315
+ printf '%s' "$exclude_added"
316
+ echo " Note: this protects only this clone — teammates opt in by running 'npx @codewizard-dt/bootstrap update' themselves."
317
+ fi
318
+ fi
319
+ else
320
+ # All three are already excluded somewhere in the file: git's behaviour does
321
+ # not change, only the picker's view of it. A pure repair, so no prompt.
322
+ if exclude_apply; then
323
+ echo " .git/info/exclude: reordered .serena/, raw/, wiki/ under the bootstrap sentinel (git unchanged; restores @-autocomplete)"
324
+ fi
325
+ fi
138
326
  fi