@codewizard-dt/bootstrap 2.20.0 → 2.21.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.
@@ -25,7 +25,7 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
25
25
  | `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
26
26
  | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
27
27
  | `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
28
- | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so the excluded paths are written under a `# bootstrap wiki & agent state (machine-local)` sentinel that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. |
28
+ | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Fully interactive `.gitignore` merge — **nothing is ever added without asking**. The packaged template's titled sections are offered one by one (`Add/update .gitignore section '<title>' (N new line(s))? [y/N]`); sections with nothing new are skipped silently. Non-interactive runs (or no tty) change nothing at all. Never touches existing project content. Also offers (git repos only) to keep `.serena/`/`raw/`/`wiki/` out of git via **`.git/info/exclude`** — never `.gitignore`, which would blind Serena on the wiki (see `wiki/knowledge/concepts/git-ignore-tool-visibility.md`); per-machine and idempotent. `info/exclude` *is* honored by ripgrep-class walkers and the `@` file picker, so every machine-local exclusion this script manages — the wiki/agent-state dirs AND the `.claude/bootstrap-prefs.*` files, whichever of its prompts get answered and in whichever order — is written under **one shared, generic sentinel** (`# bootstrap machine-local (autocomplete-visible)`) that the `fileSuggestion` picker installed by `install-global.sh` reads back to restore `@`-autocomplete. The sentinel line itself is written proactively on every interactive run against a git repo, even if every exclude-affecting prompt is declined, so the anchor is always there regardless of which preferences got set; a project still carrying the old, separately-named pre-unification header is repaired onto the shared sentinel automatically. |
29
29
  | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical permission deny list (`templates/settings-deny.json` — `Bash(...)` command patterns plus `Edit(...)`/`Read(...)` file-tool patterns) into `~/.claude/settings.json` `permissions.deny`. Entries are opaque strings, so any rule form the permission system accepts merges unchanged. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. A second mode, `--set-key <name> --set-value <json>`, merges a single top-level settings key instead of the deny list (used to register `fileSuggestion`): absent → set; already deep-equal → no-op; present but different → one-line warning and skip, never a clobber. Supplying `--set-key` skips the deny merge entirely; a malformed `--set-value` exits 1, since that is a call-site bug rather than a user's file. |
30
30
  | `merge-settings-hooks.js` | `install-global.sh` | Zero-dependency Node sibling of `merge-settings-deny.js` (deliberately not a new mode of it — different, block-and-entry-aware semantics) that merges the canonical hook wiring (`templates/settings-hooks.json`) into the `hooks` key of `~/.claude/settings.json` with a "template owns its blocks" model: repo-owned entries (a `command` under `~/.claude/hooks/` whose basename appears in the template) are created or updated in place; matcher drift on a pure-owned block is adopted (a matcher rename ships without duplicating the block); user/foreign blocks and entries are never modified, reordered, or removed; a repo hook found relocated into a mixed block is warned about but not duplicated; no empty placeholder blocks are ever written. 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. |
31
31
  | `bootstrap-prefs.js` | `install-global.sh`, `install-mcps.sh`, `sync-wiki-scaffold.sh`, `merge-gitignore.sh`, `update-project.sh` (all through the `prefs_*` / `prompt_*_sticky` wrappers in `lib.sh`), and the `/bootstrap-config` skill | Zero-dependency Node reader/writer for the preference store — the one binary every consumer goes through, so no prompt site keeps its own copy of a key's value list. Five operations: `--get` (a resolving read; always exits 0, so no call site needs `\|\| true`), `--set`, `--unset`, `--list`, and `--section-key <title>` (turns a `.gitignore` banner title into its `gitignore.section.<slug>` key, so the slug rule has exactly one implementation and is Unicode-aware). `--set`/`--unset` require **exactly one** layer selector (`--global` / `--project <dir>` / `--target <path>`) and will not guess — a misdirected write is unrecoverable in a way a misdirected read is not; `--get` resolves across layers by default for the mirror-image reason. Values are validated against the schema's `values` grammar (an illegal value exits 1 — a caller bug must never land in the file and read back as `unset`), and `--set` also refuses to write into a layer the key's `scope` forbids (`--target` stays exempt); writes are atomic and reuse the file's existing indentation; and every successful `--set`/`--unset` regenerates the `bootstrap-prefs.README.md` companion beside the values file. See [Preference helper notes](#preference-helper-notes). |
@@ -385,7 +385,7 @@ JSON; if the two ever disagree, the JSON is right and this table is a bug.
385
385
  | `mcp.playwrightConflict` | project | installer | `shared \| alongside \| skip` | `unset` | `install-mcps.sh` | How to resolve a committed `.mcp.json` that already registers its own playwright server |
386
386
  | `mcp.playwrightReplace` | project | installer | `true \| false` | `unset` | `install-mcps.sh` | Replace an existing machine-local Playwright registration with the bootstrap shared server |
387
387
  | `update.legacyDocsAck` | project | installer | `true \| false` | `unset` | `update-project.sh` | Continue `update` even though a legacy `.docs/` directory was detected |
388
- | `gitignore.infoExclude` | project | installer | `true \| false` | `unset` | `merge-gitignore.sh` | Keep `.serena/`, `raw/`, and `wiki/` out of git on this machine via `.git/info/exclude` |
388
+ | `gitignore.infoExclude` | project | installer | `true \| false` | `unset` | `merge-gitignore.sh` | Add `.serena/`, `raw/`, and `wiki/` to git's local ignore list via `.git/info/exclude` |
389
389
  | `prefs.gitTracking` | project | installer | `gitignore \| exclude \| neither` | `unset` | `merge-gitignore.sh` | How git should treat `.claude/bootstrap-prefs.json` and `bootstrap-prefs.README.md` |
390
390
  | `guides.*` **(pattern)** | project | installer | `true \| false` | `unset` | `sync-wiki-scaffold.sh` | Install a specific optional guide into `wiki/guides/` |
391
391
  | `gitignore.section.*` **(pattern)** | project | installer | `false` | `unset` | `merge-gitignore.sh` | Permanently decline one titled `.gitignore` template section |
@@ -27,7 +27,9 @@ GLOBAL_HOOKS_DIR="$HOME/.claude/hooks"
27
27
  if [ -d "$TEMPLATE_DIR/lib/hooks" ]; then
28
28
  echo "Installing hooks globally (~/.claude/hooks/)..."
29
29
  mkdir -p "$GLOBAL_HOOKS_DIR"
30
- rsync -av --exclude='.DS_Store' "$TEMPLATE_DIR/lib/hooks/" "$GLOBAL_HOOKS_DIR/"
30
+ # Content-based comparison + minimal per-file report — see sync-wiki-scaffold.sh's
31
+ # RSYNC_FLAGS comment for why plain -av re-lists every file on every run.
32
+ rsync -a --checksum --omit-dir-times --out-format=' + %n' --exclude='.DS_Store' "$TEMPLATE_DIR/lib/hooks/" "$GLOBAL_HOOKS_DIR/"
31
33
  echo ""
32
34
  else
33
35
  echo "Warning: $TEMPLATE_DIR/lib/hooks not found — hook scripts NOT installed" >&2
@@ -40,7 +42,7 @@ echo "Installing skills globally (~/.claude/skills/)..."
40
42
  mkdir -p "$GLOBAL_SKILLS_DIR"
41
43
 
42
44
  # Rsync skills from the template to ~/.claude/skills/
43
- rsync -av --exclude='.DS_Store' "$TEMPLATE_DIR/lib/skills/" "$GLOBAL_SKILLS_DIR/"
45
+ rsync -a --checksum --omit-dir-times --out-format=' + %n' --exclude='.DS_Store' "$TEMPLATE_DIR/lib/skills/" "$GLOBAL_SKILLS_DIR/"
44
46
 
45
47
  # Detect stale skill folders from the wiki rename
46
48
  ORPHAN_FOUND=()
@@ -216,6 +216,17 @@ prompt_yn() {
216
216
  fi
217
217
  case "$reply" in
218
218
  [yY]*) return 0 ;;
219
+ "")
220
+ # A bare Enter press honors whichever default the prompt text itself
221
+ # displays. Every prompt in this codebase already signals its default
222
+ # via bracket capitalization ("[Y/n]" vs "[y/N]") — this just makes an
223
+ # empty reply match what the user was shown, instead of every empty
224
+ # reply silently meaning "no" regardless of what the brackets promised.
225
+ case "$prompt" in
226
+ *"[Y/n]"*) return 0 ;;
227
+ *) return 1 ;;
228
+ esac
229
+ ;;
219
230
  *) return 1 ;;
220
231
  esac
221
232
  }
@@ -242,71 +242,107 @@ elif [ "$review_sections" -eq 1 ]; then
242
242
  echo ".gitignore: no changes made in $PROJECT_DIR"
243
243
  fi
244
244
 
245
- # Machine-local git exclusion for bootstrap agent state. These dirs must NEVER
246
- # go into .gitignore: Serena (ignore_all_files_in_gitignore: true) and Claude
247
- # Code's Grep mirror .gitignore and would go blind on the wiki. .git/info/exclude
248
- # has identical semantics for git, is never committed (a per-machine choice,
249
- # offered per-machine), and is invisible to Serena — its GitignoreParser reads
250
- # only files named ".gitignore", so the dirs stay navigable. It is NOT invisible
251
- # to every tool: ripgrep-class walkers and Claude Code's @ file picker do honor
252
- # info/exclude. That is why install-global.sh installs ~/.claude/file-suggestion.sh
253
- # and registers it as the fileSuggestion picker — it re-includes exactly the paths
254
- # listed under the sentinel written below.
245
+ # Machine-local git exclusion for bootstrap agent state and preference files.
246
+ # These dirs must NEVER go into .gitignore: Serena (ignore_all_files_in_gitignore:
247
+ # true) and Claude Code's Grep mirror .gitignore and would go blind on the wiki.
248
+ # .git/info/exclude has identical semantics for git, is never committed (a
249
+ # per-machine choice, offered per-machine), and is invisible to Serena — its
250
+ # GitignoreParser reads only files named ".gitignore", so the dirs stay
251
+ # navigable. It is NOT invisible to every tool: ripgrep-class walkers and Claude
252
+ # Code's @ file picker do honor info/exclude. That is why install-global.sh
253
+ # installs ~/.claude/file-suggestion.sh and registers it as the fileSuggestion
254
+ # picker — it re-includes exactly the paths listed under the sentinel below.
255
+ #
256
+ # ONE sentinel, shared by both mechanisms below (wiki/agent-state dirs and the
257
+ # bootstrap-prefs files), so file-suggestion.sh's single hardcoded SENTINEL
258
+ # always matches regardless of which mechanism ran, in which order, or which
259
+ # options got picked. Generic text — not "wiki", not "preferences" — because
260
+ # it's read back only by name, never by content.
255
261
  GIT_EXCLUDE="$PROJECT_DIR/.git/info/exclude"
256
- EXCLUDE_SENTINEL="# bootstrap wiki & agent state (machine-local)"
257
-
258
- # Canonical form is what file-suggestion.sh can actually parse: the sentinel
259
- # line, immediately followed by .serena/, raw/, wiki/ in that order, each of the
260
- # four appearing exactly once, and the block terminated by a "#" comment or EOF.
261
- # A path sitting ABOVE the sentinel is still excluded by git but invisible to the
262
- # picker, so appending only the absent paths is not enough — we normalize.
263
- exclude_is_canonical() {
264
- [ -f "$1" ] || return 1
265
- awk -v sentinel="$EXCLUDE_SENTINEL" '
266
- { line[NR] = $0 }
267
- $0 == sentinel { sent++; at = NR }
268
- $0 == ".serena/" { a++ }
269
- $0 == "raw/" { b++ }
270
- $0 == "wiki/" { c++ }
271
- END {
272
- if (sent != 1 || a != 1 || b != 1 || c != 1) exit 1
273
- if (line[at + 1] != ".serena/" || line[at + 2] != "raw/" || line[at + 3] != "wiki/") exit 1
274
- if (at + 3 < NR && line[at + 4] !~ /^[[:space:]]*#/) exit 1
275
- exit 0
276
- }
277
- ' "$1"
278
- }
262
+ EXCLUDE_SENTINEL="# bootstrap machine-local (autocomplete-visible)"
263
+
264
+ # The sentinel text this mechanism used before the two blocks were unified.
265
+ # Scrubbed on sight by exclude_ensure_paths so upgrading an existing project
266
+ # (like one that only ever answered the prefs.gitTracking question) cleans up
267
+ # the stale header automatically instead of leaving two competing sentinels.
268
+ LEGACY_PREFS_SENTINEL="# bootstrap preferences (machine-local)"
269
+
270
+ # Every path bootstrap ever excludes here, in the fixed order they're packed
271
+ # into the block when present. Each is independently optional — the block can
272
+ # hold anywhere from zero of these (the proactive empty case) to all five.
273
+ KNOWN_EXCLUDE_PATHS=(".serena/" "raw/" "wiki/" ".claude/bootstrap-prefs.json" ".claude/bootstrap-prefs.README.md")
274
+
275
+ # Set by exclude_ensure_paths after every call: 1 if the file's content changed,
276
+ # 0 if it was already exactly the desired shape (byte-identical, left untouched
277
+ # — mtime and permissions included). Callers use this to decide whether a
278
+ # repair/no-op message is worth printing.
279
+ EXCLUDE_CHANGED=0
279
280
 
280
- # A user's own entry sitting INSIDE the sentinel block. Normalizing re-appends
281
- # our block at the bottom and leaves such an entry above it: git still excludes
282
- # it, but the picker stops re-including it, so say so rather than change the
283
- # user's view of their own file silently.
281
+ # A user's own entry sitting INSIDE the sentinel block that isn't one of
282
+ # KNOWN_EXCLUDE_PATHS. exclude_ensure_paths re-appends our block at the bottom
283
+ # and leaves such an entry above it: git still excludes it, but the picker stops
284
+ # re-including it, so say so rather than change the user's view of their own
285
+ # file silently.
284
286
  exclude_stranded() {
285
287
  [ -f "$1" ] || return 0
286
- awk -v sentinel="$EXCLUDE_SENTINEL" '
288
+ # Space-joined, not newline-joined: BSD awk (macOS's default /usr/bin/awk)
289
+ # rejects a `-v` value containing an embedded newline ("newline in string").
290
+ # None of KNOWN_EXCLUDE_PATHS' fixed entries contain a space, so this is safe.
291
+ awk -v sentinel="$EXCLUDE_SENTINEL" -v known="$(printf '%s ' "${KNOWN_EXCLUDE_PATHS[@]}")" '
292
+ BEGIN { kc = split(known, klines, " ") }
287
293
  $0 == sentinel { in_block = 1; next }
288
294
  in_block && /^[[:space:]]*#/ { in_block = 0 }
289
- in_block && $0 !~ /^[[:space:]]*$/ \
290
- && $0 != ".serena/" && $0 != "raw/" && $0 != "wiki/" { print " " $0 }
295
+ in_block && $0 !~ /^[[:space:]]*$/ {
296
+ is_known = 0
297
+ for (i = 1; i <= kc; i++) if ($0 == klines[i]) { is_known = 1; break }
298
+ if (!is_known) print " " $0
299
+ }
291
300
  ' "$1"
292
301
  }
293
302
 
294
- # Scrub every occurrence of the sentinel and of the three exact whole-line paths
295
- # from anywhere in the file, then re-append the canonical block at the bottom.
296
- # Every other line survives verbatim and in its original order (this file may
297
- # hold the user's own exclusions); only a blank run the scrub itself created is
298
- # collapsed, and the result ends with exactly one newline.
299
- exclude_normalize() {
300
- local file="$1" src="$1" tmp mode=""
303
+ # exclude_ensure_paths <file> [path...]: idempotently ensure the sentinel is
304
+ # present in <file> exactly once, immediately followed by every
305
+ # KNOWN_EXCLUDE_PATHS entry that is either already anywhere in the file (so a
306
+ # prior run's, or the other mechanism's, entries survive) or passed as an
307
+ # argument here — packed in KNOWN_EXCLUDE_PATHS order, terminated by a "#"
308
+ # comment or EOF. Everything else in the file survives verbatim and in its
309
+ # original relative order (this file may hold the user's own exclusions); the
310
+ # legacy pre-unification header is scrubbed on sight. A file already in exactly
311
+ # this shape is left byte-identical (EXCLUDE_CHANGED=0) so repeated/no-op calls
312
+ # never show up as a diff.
313
+ exclude_ensure_paths() {
314
+ local file="$1"; shift
315
+ local src="$file" tmp mode="" p a
316
+ local want=()
301
317
  [ -f "$src" ] || src=/dev/null
318
+
319
+ for p in "${KNOWN_EXCLUDE_PATHS[@]}"; do
320
+ if [ -f "$src" ] && grep -qFx -- "$p" "$src"; then
321
+ want+=("$p")
322
+ continue
323
+ fi
324
+ for a in "$@"; do
325
+ if [ "$a" = "$p" ]; then want+=("$p"); break; fi
326
+ done
327
+ done
328
+
302
329
  if [ -f "$file" ]; then
303
330
  mode=$(stat -f '%Lp' "$file" 2>/dev/null || stat -c '%a' "$file" 2>/dev/null || true)
304
331
  fi
305
332
  mkdir -p "$(dirname "$file")" || return 1
306
333
  tmp=$(mktemp "$(dirname "$file")/.bootstrap-exclude.XXXXXX") || return 1
307
- awk -v sentinel="$EXCLUDE_SENTINEL" '
308
- BEGIN { n = 0; prev_blank = 1; dropped = 0 }
309
- $0 == sentinel || $0 == ".serena/" || $0 == "raw/" || $0 == "wiki/" { dropped = 1; next }
334
+ # Space-joined, not newline-joined: BSD awk (macOS's default /usr/bin/awk)
335
+ # rejects a `-v` value containing an embedded newline ("newline in string").
336
+ # `want` only ever holds entries from the fixed, space-free KNOWN_EXCLUDE_PATHS.
337
+ awk -v sentinel="$EXCLUDE_SENTINEL" -v legacy="$LEGACY_PREFS_SENTINEL" \
338
+ -v wanted="$(printf '%s ' ${want[@]+"${want[@]}"})" '
339
+ BEGIN { n = 0; prev_blank = 1; dropped = 0; wc = split(wanted, wlines, " ") }
340
+ $0 == sentinel || $0 == legacy { dropped = 1; next }
341
+ {
342
+ is_known = 0
343
+ for (i = 1; i <= wc; i++) if (wlines[i] != "" && $0 == wlines[i]) { is_known = 1; break }
344
+ }
345
+ is_known { dropped = 1; next }
310
346
  {
311
347
  if ($0 ~ /^[[:space:]]*$/) {
312
348
  if (prev_blank && dropped) next
@@ -322,23 +358,29 @@ exclude_normalize() {
322
358
  if (n == 1 && keep[1] ~ /^[[:space:]]*$/) n = 0
323
359
  for (i = 1; i <= n; i++) print keep[i]
324
360
  print sentinel
325
- print ".serena/"
326
- print "raw/"
327
- print "wiki/"
361
+ for (i = 1; i <= wc; i++) if (wlines[i] != "") print wlines[i]
328
362
  }
329
363
  ' "$src" > "$tmp" || { rm -f "$tmp"; return 1; }
364
+
365
+ if [ -f "$file" ] && cmp -s "$file" "$tmp"; then
366
+ rm -f "$tmp"
367
+ EXCLUDE_CHANGED=0
368
+ return 0
369
+ fi
330
370
  mv -f "$tmp" "$file" || { rm -f "$tmp"; return 1; }
331
371
  if [ -n "$mode" ]; then chmod "$mode" "$file" 2>/dev/null || true; fi
372
+ EXCLUDE_CHANGED=1
332
373
  return 0
333
374
  }
334
375
 
335
376
  # Normalize and report. Never fatal: this runs under `set -euo pipefail` from
336
377
  # run_project_sync and must not abort the user's setup.
337
378
  exclude_apply() {
379
+ local file="$1"; shift
338
380
  local stranded
339
- stranded=$(exclude_stranded "$GIT_EXCLUDE")
340
- if ! exclude_normalize "$GIT_EXCLUDE"; then
341
- echo " Warning: could not update $GIT_EXCLUDE — left unchanged."
381
+ stranded=$(exclude_stranded "$file")
382
+ if ! exclude_ensure_paths "$file" "$@"; then
383
+ echo " Warning: could not update $file — left unchanged."
342
384
  return 1
343
385
  fi
344
386
  if [ -n "$stranded" ]; then
@@ -349,7 +391,30 @@ exclude_apply() {
349
391
  return 0
350
392
  }
351
393
 
394
+ # Guarantees the shared sentinel exists even if nothing is excluded yet, so any
395
+ # bootstrap feature — this run or a future one — always finds the same anchor
396
+ # regardless of which of the prompts below get accepted or declined. A bare
397
+ # comment line excludes nothing, so writing it needs no consent prompt. Stays
398
+ # quiet unless this call is what introduces the sentinel for the very first
399
+ # time on a file with no bootstrap-managed paths yet — otherwise the branches
400
+ # below describe whatever they changed themselves.
401
+ exclude_ensure_sentinel() {
402
+ local file="$1" had_sentinel=false had_known=false p
403
+ if [ -f "$file" ]; then
404
+ grep -qFx -- "$EXCLUDE_SENTINEL" "$file" 2>/dev/null && had_sentinel=true
405
+ for p in "${KNOWN_EXCLUDE_PATHS[@]}"; do
406
+ grep -qFx -- "$p" "$file" 2>/dev/null && { had_known=true; break; }
407
+ done
408
+ fi
409
+ exclude_apply "$file" || return 0
410
+ if [ "$EXCLUDE_CHANGED" -eq 1 ] && [ "$had_sentinel" = false ] && [ "$had_known" = false ]; then
411
+ echo " .git/info/exclude: added shared bootstrap sentinel (machine-local; nothing excluded yet)"
412
+ fi
413
+ }
414
+
352
415
  if [ -d "$PROJECT_DIR/.git" ]; then
416
+ exclude_ensure_sentinel "$GIT_EXCLUDE"
417
+
353
418
  exclude_missing=0
354
419
  exclude_added=""
355
420
  for p in ".serena/" "raw/" "wiki/"; do
@@ -360,21 +425,20 @@ if [ -d "$PROJECT_DIR/.git" ]; then
360
425
  exclude_added="${exclude_added} + ${p} (.git/info/exclude)"$'\n'
361
426
  done
362
427
 
363
- if exclude_is_canonical "$GIT_EXCLUDE"; then
364
- : # already canonical — leave the file byte-identical
365
- elif [ "$exclude_missing" -gt 0 ]; then
428
+ if [ "$exclude_missing" -gt 0 ]; then
366
429
  # Accepting newly hides paths from git, so this stays a consent prompt.
367
430
  #
368
431
  # `gitignore.infoExclude` is declines-only: a decline records `false` and
369
432
  # suppresses the re-offer, an accept records NOTHING, because accepting
370
- # changes the world and `exclude_is_canonical` above already makes it
371
- # sticky. Keep this key distinct from `gitignore.offerSectionUpdates` (the
372
- # .gitignore section pass) and `prefs.gitTracking` (the preference files
373
- # themselves) — declining one must never disable another.
433
+ # changes the world and exclude_ensure_paths's byte-identical no-op above
434
+ # already makes it sticky. Keep this key distinct from
435
+ # `gitignore.offerSectionUpdates` (the .gitignore section pass) and
436
+ # `prefs.gitTracking` (the preference files themselves) — declining one must
437
+ # never disable another.
374
438
  if [ "$(prefs_get gitignore.infoExclude "$PROJECT_DIR")" = "false" ]; then
375
439
  echo " .git/info/exclude: skipped (remembered answer gitignore.infoExclude=false — change with /bootstrap-config)."
376
- elif 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
377
- if exclude_apply; then
440
+ elif prompt_yn " Add .serena/, raw/, and wiki/ to git's local ignore list (.git/info/exclude, this machine only)? [y/N]: "; then
441
+ if exclude_apply "$GIT_EXCLUDE" ".serena/" "raw/" "wiki/"; then
378
442
  printf '%s' "$exclude_added"
379
443
  echo " Note: this protects only this clone — teammates opt in by running 'npx @codewizard-dt/bootstrap update' themselves."
380
444
  fi
@@ -386,7 +450,9 @@ if [ -d "$PROJECT_DIR/.git" ]; then
386
450
  # not change, only the picker's view of it. A pure repair, so no prompt —
387
451
  # deliberately regardless of the stored `gitignore.infoExclude` value, since
388
452
  # a decline refuses newly hiding paths, not repairing a sentinel.
389
- if exclude_apply; then
453
+ # exclude_apply is a byte-identical no-op when the block is already
454
+ # canonical, so EXCLUDE_CHANGED gates the message.
455
+ if exclude_apply "$GIT_EXCLUDE" ".serena/" "raw/" "wiki/" && [ "$EXCLUDE_CHANGED" -eq 1 ]; then
390
456
  echo " .git/info/exclude: reordered .serena/, raw/, wiki/ under the bootstrap sentinel (git unchanged; restores @-autocomplete)"
391
457
  fi
392
458
  fi
@@ -466,42 +532,33 @@ if has_tty; then
466
532
  echo " .git/info/exclude: $PROJECT_DIR is not a git repository — nothing to exclude; the preference files stay visible to git."
467
533
  else
468
534
  prefs_written=0
535
+ prefs_added=""
469
536
  for p in "$PREFS_VALUES_PATH" "$PREFS_README_PATH"; do
470
537
  if [ -f "$GIT_EXCLUDE" ] && grep -qFx -- "$p" "$GIT_EXCLUDE"; then
471
538
  continue
472
539
  fi
540
+ prefs_written=$((prefs_written + 1))
541
+ prefs_added="${prefs_added} + ${p} (.git/info/exclude)"$'\n'
542
+ done
543
+ # Same shared sentinel and merge function the wiki-dirs block above
544
+ # uses — both mechanisms converge on one block so file-suggestion.sh's
545
+ # single hardcoded SENTINEL always matches, regardless of which of the
546
+ # two ran first or which options were chosen. exclude_ensure_paths only
547
+ # adds paths it's asked for (or that were already present), so this
548
+ # never force-adds .serena/, raw/, or wiki/ for a user who declined
549
+ # that separately — and it scrubs the legacy pre-unification header on
550
+ # sight if this project still has it.
551
+ if exclude_apply "$GIT_EXCLUDE" "$PREFS_VALUES_PATH" "$PREFS_README_PATH"; then
473
552
  if [ "$prefs_written" -eq 0 ]; then
474
- mkdir -p "$(dirname "$GIT_EXCLUDE")"
475
- if [ -s "$GIT_EXCLUDE" ] && [ -n "$(tail -c1 "$GIT_EXCLUDE")" ]; then
476
- printf '\n' >> "$GIT_EXCLUDE"
553
+ if [ "$EXCLUDE_CHANGED" -eq 1 ]; then
554
+ echo " .git/info/exclude: already excludes the bootstrap preference files (repositioned under the shared bootstrap sentinel)."
555
+ else
556
+ echo " .git/info/exclude: already excludes the bootstrap preference files."
477
557
  fi
478
- # Their OWN "#" header, never bare. Two things depend on it: the
479
- # block above may already have normalized the sentinel block to the
480
- # bottom of this file, and a "#" line directly after wiki/ is exactly
481
- # what exclude_is_canonical accepts as the block terminator; and
482
- # exclude_stranded stops scanning at the first "#", so our entries
483
- # are never reported as stranded inside the bootstrap block.
484
- printf '# bootstrap preferences (machine-local)\n' >> "$GIT_EXCLUDE"
558
+ else
559
+ printf '%s' "$prefs_added"
560
+ echo " Note: this hides them on THIS machine only — teammates are unaffected."
485
561
  fi
486
- printf '%s\n' "$p" >> "$GIT_EXCLUDE"
487
- echo " + $p (.git/info/exclude)"
488
- prefs_written=$((prefs_written + 1))
489
- done
490
- if [ "$prefs_written" -eq 0 ]; then
491
- echo " .git/info/exclude: already excludes the bootstrap preference files."
492
- else
493
- echo " Note: this hides them on THIS machine only — teammates are unaffected."
494
- fi
495
- # Verify rather than trust: a file left non-canonical is silently
496
- # rewritten by exclude_normalize on every future run. Repair ONLY when
497
- # the sentinel is already present — exclude_apply would otherwise create
498
- # the block and hide .serena/, raw/, wiki/ from a user who just declined
499
- # exactly that above. A later normalize pass leaves our lines intact,
500
- # because its scrub only removes the sentinel and those three paths.
501
- if [ -f "$GIT_EXCLUDE" ] \
502
- && grep -qFx -- "$EXCLUDE_SENTINEL" "$GIT_EXCLUDE" \
503
- && ! exclude_is_canonical "$GIT_EXCLUDE"; then
504
- exclude_apply || true
505
562
  fi
506
563
  fi
507
564
  ;;
@@ -75,7 +75,7 @@ fi
75
75
  # the topology the scaffolded CI implements. Landed before the Claude run so
76
76
  # it survives a timeout.
77
77
  mkdir -p "$PROJECT_DIR/wiki/guides"
78
- rsync -av "$GUIDE" "$PROJECT_DIR/wiki/guides/deployment-strategy.md"
78
+ rsync -a --checksum --out-format=' + %n' "$GUIDE" "$PROJECT_DIR/wiki/guides/deployment-strategy.md"
79
79
 
80
80
  TASK="$(sed "s|__PROJECT_DIR__|$PROJECT_DIR|g" "$TEMPLATE")"
81
81
 
@@ -45,19 +45,26 @@ mkdir -p \
45
45
  "$PROJECT_DIR/wiki/work/bugs" \
46
46
  "$PROJECT_DIR/wiki/guides"
47
47
 
48
+ # rsync flags shared by every call below: content-based comparison (not
49
+ # mtime — each `npx` run extracts a fresh package copy with new mtimes, which
50
+ # would otherwise make every file look "changed" on every run), no directory
51
+ # mtime writes (same reason, applied to directories), and a minimal one-line
52
+ # report per file actually transferred instead of the full recursive listing.
53
+ RSYNC_FLAGS=(-a --checksum --omit-dir-times --out-format=' + %n')
54
+
48
55
  # 2. COPY-ONCE: index.md, log.md, hot.md, .gitkeep files — project-owned after creation, never overwrite
49
56
  # Exclude conventions.md and lifecycle.md (those are always-refresh, handled in step 3).
50
- rsync -av --ignore-existing \
57
+ rsync "${RSYNC_FLAGS[@]}" --ignore-existing \
51
58
  --exclude 'conventions.md' \
52
59
  --exclude 'lifecycle.md' \
53
60
  --exclude 'dashboard.html' \
54
61
  "$TEMPLATES/" "$PROJECT_DIR/wiki/"
55
62
 
56
63
  # 3. ALWAYS-REFRESH: spec docs (conventions.md, lifecycle.md) and dashboard.html that remain template-owned; always overwrite
57
- rsync -av "$TEMPLATES/conventions.md" "$PROJECT_DIR/wiki/conventions.md"
58
- rsync -av "$TEMPLATES/dashboard.html" "$PROJECT_DIR/wiki/dashboard.html"
64
+ rsync "${RSYNC_FLAGS[@]}" "$TEMPLATES/conventions.md" "$PROJECT_DIR/wiki/conventions.md"
65
+ rsync "${RSYNC_FLAGS[@]}" "$TEMPLATES/dashboard.html" "$PROJECT_DIR/wiki/dashboard.html"
59
66
  for fam in requirements decisions roadmaps tasks uat bugs; do
60
- rsync -av "$TEMPLATES/work/$fam/lifecycle.md" "$PROJECT_DIR/wiki/work/$fam/lifecycle.md"
67
+ rsync "${RSYNC_FLAGS[@]}" "$TEMPLATES/work/$fam/lifecycle.md" "$PROJECT_DIR/wiki/work/$fam/lifecycle.md"
61
68
  done
62
69
 
63
70
  # 4. GUIDES: tiered delivery into target wiki/guides/ (template-owned
@@ -83,9 +90,9 @@ OPTIONAL_GUIDES="evals-framework.md type-checking-templates"
83
90
  deliver_guide() {
84
91
  # $1 = guide name (file or dir under GUIDES_SRC)
85
92
  if [ -d "$GUIDES_SRC/$1" ]; then
86
- rsync -av "$GUIDES_SRC/$1/" "$GUIDES_DST/$1/"
93
+ rsync "${RSYNC_FLAGS[@]}" "$GUIDES_SRC/$1/" "$GUIDES_DST/$1/"
87
94
  else
88
- rsync -av "$GUIDES_SRC/$1" "$GUIDES_DST/"
95
+ rsync "${RSYNC_FLAGS[@]}" "$GUIDES_SRC/$1" "$GUIDES_DST/"
89
96
  fi
90
97
  }
91
98
 
@@ -47,8 +47,8 @@
47
47
  "gitignore.infoExclude": {
48
48
  "scope": "project",
49
49
  "consumer": "installer",
50
- "summary": "Keep .serena/, raw/, and wiki/ out of git on this machine via .git/info/exclude",
51
- "detail": "Asked by merge-gitignore.sh:376 when one or more of .serena/, raw/, wiki/ are not yet excluded. true writes them under the bootstrap sentinel in .git/info/exclude — machine-local, never committed, and unlike .gitignore it does not blind Serena or ripgrep-class walkers; the installed fileSuggestion script restores @-autocomplete for those paths. false leaves git tracking them here; teammates opt in separately by running update themselves. This is INDEPENDENT of the .gitignore section pass governed by gitignore.offerSectionUpdates: declining or disabling sections never disables the info/exclude mechanism, and a pure sentinel repair (all three already excluded elsewhere in the file) runs with no prompt at all regardless of this key. See also prefs.gitTracking, which decides how git treats the preferences file itself — a different question from these three directories.",
50
+ "summary": "Add .serena/, raw/, and wiki/ to git's local ignore list via .git/info/exclude",
51
+ "detail": "Asked by merge-gitignore.sh:440 when one or more of .serena/, raw/, wiki/ are not yet excluded. true writes them under the bootstrap sentinel in .git/info/exclude — machine-local, never committed, and unlike .gitignore it does not blind Serena or ripgrep-class walkers; the installed fileSuggestion script restores @-autocomplete for those paths. false leaves git tracking them here; teammates opt in separately by running update themselves. This is INDEPENDENT of the .gitignore section pass governed by gitignore.offerSectionUpdates: declining or disabling sections never disables the info/exclude mechanism, and a pure sentinel repair (all three already excluded elsewhere in the file) runs with no prompt at all regardless of this key. See also prefs.gitTracking, which decides how git treats the preferences file itself — a different question from these three directories.",
52
52
  "values": "true | false",
53
53
  "default": null,
54
54
  "askedBy": "merge-gitignore.sh"
@@ -66,7 +66,7 @@
66
66
  "scope": "project",
67
67
  "consumer": "installer",
68
68
  "summary": "Install a specific optional guide into wiki/guides/",
69
- "detail": "One key per entry in sync-wiki-scaffold.sh's OPTIONAL_GUIDES list (sync-wiki-scaffold.sh:81), keyed by the exact entry text including any extension — today that is guides.evals-framework.md and guides.type-checking-templates. true delivers the guide into wiki/guides/ on every run; false keeps it out and suppresses the per-run prompt. A guide already present in wiki/guides/ (or in the legacy .docs/guides/) is refreshed regardless of this key — existing opt-in wins, because the file on disk is the stronger signal than a stored answer. The required guide tier is never gated by these keys.",
69
+ "detail": "One key per entry in sync-wiki-scaffold.sh's OPTIONAL_GUIDES list (sync-wiki-scaffold.sh:88), keyed by the exact entry text including any extension — today that is guides.evals-framework.md and guides.type-checking-templates. true delivers the guide into wiki/guides/ on every run; false keeps it out and suppresses the per-run prompt. A guide already present in wiki/guides/ (or in the legacy .docs/guides/) is refreshed regardless of this key — existing opt-in wins, because the file on disk is the stronger signal than a stored answer. The required guide tier is never gated by these keys.",
70
70
  "values": "true | false",
71
71
  "default": null,
72
72
  "askedBy": "sync-wiki-scaffold.sh",
@@ -104,7 +104,7 @@
104
104
  "scope": "global",
105
105
  "consumer": "installer",
106
106
  "summary": "Registration scope for the Context7 MCP",
107
- "detail": "Asked by prompt_scope in lib.sh:393 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
107
+ "detail": "Asked by prompt_scope in lib.sh:404 ('Scope for context7 — [u]ser (default) or [p]roject?'). prompt_scope emits exactly two answers, 'user' and 'project' — it has no local-scope branch, and any reply that does not begin with p or P falls through to user. 'user' registers Context7 once for every project on this machine; 'project' writes the registration into the current project's shareable .mcp.json.",
108
108
  "values": "user | project",
109
109
  "default": null,
110
110
  "askedBy": "lib.sh"
@@ -140,7 +140,7 @@
140
140
  "scope": "global",
141
141
  "consumer": "installer",
142
142
  "summary": "Delete stale skill folders in ~/.claude/skills/ left by the wiki rename",
143
- "detail": "Asked by install-global.sh:70 when any renamed-away skill folder (the adr-* and prd-* families) is still present in ~/.claude/skills/. true removes those folders with rm -rf; false keeps them, and they continue to appear as duplicate slash commands alongside their renamed replacements. The list of orphan names is fixed in the script — this key does not decide which folders qualify, only whether the deletion runs.",
143
+ "detail": "Asked by install-global.sh:72 when any renamed-away skill folder (the adr-* and prd-* families) is still present in ~/.claude/skills/. true removes those folders with rm -rf; false keeps them, and they continue to appear as duplicate slash commands alongside their renamed replacements. The list of orphan names is fixed in the script — this key does not decide which folders qualify, only whether the deletion runs.",
144
144
  "values": "true | false",
145
145
  "default": null,
146
146
  "askedBy": "install-global.sh"
@@ -7,9 +7,16 @@
7
7
  # .git/info/exclude (and recent versions suggest only git-tracked files), so the
8
8
  # machine-local excludes written by merge-gitignore.sh blind @-autocomplete on
9
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.
10
+ # under the ONE shared bootstrap sentinel in .git/info/exclude — a user's other
11
+ # deliberately hidden entries stay hidden, and a project with no sentinel block
12
+ # gets plain `rg --files` behaviour. merge-gitignore.sh writes every
13
+ # machine-local exclusion it manages (wiki/agent-state dirs AND the
14
+ # bootstrap-prefs files) under this same sentinel, regardless of which of its
15
+ # prompts got answered or in what order — but re-inclusion below only ever
16
+ # checks `-d`, so of those, only the directories (.serena/, raw/, wiki/) come
17
+ # back in suggestions; the bootstrap-prefs files are plain files and are
18
+ # silently skipped, staying git-excluded but @-invisible. That's intentional,
19
+ # not a bug.
13
20
  #
14
21
  # Contract (community-verified; not fully spelled out in the settings docs):
15
22
  # stdin JSON object with a "query" field
@@ -23,7 +30,7 @@
23
30
  # stdout only, and stray stderr is visible noise on every keystroke.
24
31
  exec 2>/dev/null
25
32
 
26
- SENTINEL='# bootstrap wiki & agent state (machine-local)'
33
+ SENTINEL='# bootstrap machine-local (autocomplete-visible)'
27
34
  MAX_RESULTS=15
28
35
 
29
36
  # --- query -------------------------------------------------------------------
@@ -58,7 +65,8 @@ list_base() {
58
65
 
59
66
  # --- sentinel-scoped re-inclusion -------------------------------------------
60
67
  # 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/.
68
+ # line (or EOF) in .git/info/exclude — expected values are .serena/, raw/,
69
+ # wiki/, and (skipped below by the `-d` check) the two bootstrap-prefs files.
62
70
  sentinel_entries() {
63
71
  [ -f .git/info/exclude ] || return 0
64
72
  awk -v sentinel="$SENTINEL" '
@@ -29,9 +29,15 @@ Bootstrap remembers your answers to installer and skill prompts in two flat JSON
29
29
 
30
30
  ## Step A — Locate the helper, the schema, and the layers
31
31
 
32
- 1. Resolve the helper path. Prefer `lib/scripts/bootstrap-prefs.js` relative to the current project root; if the current project is not this repo, fall back to the installed copy that ships with the bootstrap package. If neither exists, abort with this exact message and stop:
32
+ 1. Resolve the helper path. There are exactly two valid locations — never search anywhere else, and never search under a project's own `lib/scripts/` (that path exists only inside the bootstrap-claude source repo checkout itself, never in a project that merely installed it):
33
+ - **If the current project is this bootstrap-claude repo itself** (dev checkout — `lib/scripts/bootstrap-prefs.js` exists relative to the project root): use that repo-local copy.
34
+ - **Otherwise (any installed/target project, the common case):** the helper lives at the fixed, project-independent path `~/.claude/bootstrap-prefs.js`, installed there by `install-global.sh` precisely so it's reachable from arbitrary projects. Use that path directly — do not `ls`/`find` for it first.
35
+ - If neither location has the file, abort with this exact message and stop:
33
36
  > No bootstrap preference helper found. Run `npx @codewizard-dt/bootstrap update` (or `./lib/scripts/install-global.sh --skip-mcps`) to install it, then re-run `/bootstrap-config`.
34
- 2. Resolve the schema path: `lib/scripts/templates/bootstrap-prefs-schema.json`, sitting next to the helper. The helper already defaults to exactly that path, so pass `--schema <path>` **only** when a non-default schema was located.
37
+ 2. Resolve the schema path — it is **not** beside the helper when installed:
38
+ - Repo-local case: `lib/scripts/templates/bootstrap-prefs-schema.json`.
39
+ - Installed case: `~/.claude/templates/bootstrap-prefs-schema.json`. (The helper resolves the schema as `<its own dir>/templates/...`, and the installer deliberately places it there — see `install-global.sh`'s step 6 comment.)
40
+ The helper already defaults to the path matching its own location, so pass `--schema <path>` **only** when a non-default schema was located.
35
41
  3. Determine `PROJECT_DIR` — the current working directory when inside a git repo / project, otherwise none. Record whether each layer's file exists:
36
42
  - project layer: `<PROJECT_DIR>/.claude/bootstrap-prefs.json`
37
43
  - global layer: `~/.claude/bootstrap-prefs.json`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@codewizard-dt/bootstrap",
3
- "version": "2.20.0",
3
+ "version": "2.21.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": {