@codewizard-dt/bootstrap 2.10.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 (186) hide show
  1. package/.github/workflows/build.yml +88 -0
  2. package/.github/workflows/security.yml +24 -0
  3. package/.gitleaks.toml +15 -0
  4. package/README.md +472 -0
  5. package/bin/cli.js +47 -0
  6. package/lib/README.md +27 -0
  7. package/lib/hooks/README.md +316 -0
  8. package/lib/hooks/env-file-guard.js +45 -0
  9. package/lib/hooks/git-protected-ops-block.js +77 -0
  10. package/lib/hooks/lib/serena-languages.js +158 -0
  11. package/lib/hooks/lib/serena.js +787 -0
  12. package/lib/hooks/mv-absolute-path-block.js +53 -0
  13. package/lib/hooks/serena-bash-grep-block.js +501 -0
  14. package/lib/hooks/serena-edit-guard.js +74 -0
  15. package/lib/hooks/serena-first-glob-guard.js +94 -0
  16. package/lib/hooks/serena-first-guard.js +74 -0
  17. package/lib/hooks/serena-first-read-guard.js +167 -0
  18. package/lib/hooks/serena-pre-delegation.js +117 -0
  19. package/lib/hooks/serena-session-reset.js +45 -0
  20. package/lib/hooks/serena-usage-tracker.js +186 -0
  21. package/lib/hooks/serena-write-guard.js +58 -0
  22. package/lib/prompts/README.md +16 -0
  23. package/lib/prompts/migrate-wiki.md +111 -0
  24. package/lib/prompts/setup-deployment.md +322 -0
  25. package/lib/prompts/setup-design-system.md +162 -0
  26. package/lib/prompts/setup-strict-typechecks.md +139 -0
  27. package/lib/scripts/README.md +49 -0
  28. package/lib/scripts/bootstrap-serena.sh +145 -0
  29. package/lib/scripts/build-mcp-guide.sh +108 -0
  30. package/lib/scripts/install-global.sh +78 -0
  31. package/lib/scripts/install-mcps.sh +131 -0
  32. package/lib/scripts/lib.sh +154 -0
  33. package/lib/scripts/merge-gitignore.sh +65 -0
  34. package/lib/scripts/migrate-project.sh +273 -0
  35. package/lib/scripts/setup-deployment.sh +104 -0
  36. package/lib/scripts/setup-project.sh +55 -0
  37. package/lib/scripts/setup-runner.sh +99 -0
  38. package/lib/scripts/setup-strict-typechecks.sh +29 -0
  39. package/lib/scripts/startup.sh +42 -0
  40. package/lib/scripts/sync-wiki-scaffold.sh +104 -0
  41. package/lib/scripts/templates/CLAUDE-env-safety.md +3 -0
  42. package/lib/scripts/templates/CLAUDE-wiki.md +60 -0
  43. package/lib/scripts/templates/gitignore +136 -0
  44. package/lib/scripts/templates/guides/stubs/00-header.md +15 -0
  45. package/lib/scripts/templates/guides/stubs/brave-search.md +20 -0
  46. package/lib/scripts/templates/guides/stubs/context7.md +26 -0
  47. package/lib/scripts/templates/guides/stubs/playwright.md +26 -0
  48. package/lib/scripts/templates/guides/stubs/serena.md +219 -0
  49. package/lib/scripts/templates/wiki/conventions.md +100 -0
  50. package/lib/scripts/templates/wiki/dashboard.html +1733 -0
  51. package/lib/scripts/templates/wiki/hot.md +21 -0
  52. package/lib/scripts/templates/wiki/index.md +46 -0
  53. package/lib/scripts/templates/wiki/knowledge/concepts/.gitkeep +0 -0
  54. package/lib/scripts/templates/wiki/knowledge/entities/components/.gitkeep +0 -0
  55. package/lib/scripts/templates/wiki/knowledge/entities/organisations/.gitkeep +0 -0
  56. package/lib/scripts/templates/wiki/knowledge/entities/people/.gitkeep +0 -0
  57. package/lib/scripts/templates/wiki/knowledge/entities/tools/.gitkeep +0 -0
  58. package/lib/scripts/templates/wiki/knowledge/sources/.gitkeep +0 -0
  59. package/lib/scripts/templates/wiki/log.md +14 -0
  60. package/lib/scripts/templates/wiki/work/bugs/.gitkeep +0 -0
  61. package/lib/scripts/templates/wiki/work/bugs/archive/index.md +6 -0
  62. package/lib/scripts/templates/wiki/work/bugs/index.md +12 -0
  63. package/lib/scripts/templates/wiki/work/bugs/lifecycle.md +39 -0
  64. package/lib/scripts/templates/wiki/work/decisions/.gitkeep +0 -0
  65. package/lib/scripts/templates/wiki/work/decisions/archive/index.md +6 -0
  66. package/lib/scripts/templates/wiki/work/decisions/index.md +12 -0
  67. package/lib/scripts/templates/wiki/work/decisions/lifecycle.md +42 -0
  68. package/lib/scripts/templates/wiki/work/requirements/.gitkeep +0 -0
  69. package/lib/scripts/templates/wiki/work/requirements/archive/index.md +6 -0
  70. package/lib/scripts/templates/wiki/work/requirements/index.md +12 -0
  71. package/lib/scripts/templates/wiki/work/requirements/lifecycle.md +34 -0
  72. package/lib/scripts/templates/wiki/work/roadmaps/.gitkeep +0 -0
  73. package/lib/scripts/templates/wiki/work/roadmaps/archive/index.md +6 -0
  74. package/lib/scripts/templates/wiki/work/roadmaps/index.md +12 -0
  75. package/lib/scripts/templates/wiki/work/roadmaps/lifecycle.md +32 -0
  76. package/lib/scripts/templates/wiki/work/tasks/.gitkeep +0 -0
  77. package/lib/scripts/templates/wiki/work/tasks/archive/index.md +6 -0
  78. package/lib/scripts/templates/wiki/work/tasks/index.md +12 -0
  79. package/lib/scripts/templates/wiki/work/tasks/lifecycle.md +39 -0
  80. package/lib/scripts/templates/wiki/work/uat/.gitkeep +0 -0
  81. package/lib/scripts/templates/wiki/work/uat/archive/index.md +6 -0
  82. package/lib/scripts/templates/wiki/work/uat/index.md +12 -0
  83. package/lib/scripts/templates/wiki/work/uat/lifecycle.md +48 -0
  84. package/lib/scripts/templates/wiki/work/uat/screenshots/.gitkeep +0 -0
  85. package/lib/scripts/update-project.sh +75 -0
  86. package/lib/scripts/wiki-dashboard-server.js +146 -0
  87. package/lib/skills/README.md +146 -0
  88. package/lib/skills/anti-slop/SKILL.md +183 -0
  89. package/lib/skills/bug-close/SKILL.md +136 -0
  90. package/lib/skills/bug-file/SKILL.md +114 -0
  91. package/lib/skills/bug-triage/SKILL.md +140 -0
  92. package/lib/skills/company-align/SKILL.md +203 -0
  93. package/lib/skills/debug-logs/SKILL.md +129 -0
  94. package/lib/skills/decision-create/SKILL.md +220 -0
  95. package/lib/skills/decision-finalize/SKILL.md +181 -0
  96. package/lib/skills/decision-next/SKILL.md +129 -0
  97. package/lib/skills/decision-walkthrough/SKILL.md +169 -0
  98. package/lib/skills/demo/SKILL.md +183 -0
  99. package/lib/skills/elevator-pitch/SKILL.md +125 -0
  100. package/lib/skills/eval-create/SKILL.md +344 -0
  101. package/lib/skills/eval-gap/SKILL.md +150 -0
  102. package/lib/skills/eval-run/SKILL.md +214 -0
  103. package/lib/skills/extract-feature/SKILL.md +344 -0
  104. package/lib/skills/flashcard/SKILL.md +513 -0
  105. package/lib/skills/frontend-taste/SKILL.md +184 -0
  106. package/lib/skills/gap-assess/SKILL.md +97 -0
  107. package/lib/skills/git-commit/SKILL.md +164 -0
  108. package/lib/skills/lint/SKILL.md +99 -0
  109. package/lib/skills/marp-slideshow/SKILL.md +212 -0
  110. package/lib/skills/mermaid-flowchart/SKILL.md +194 -0
  111. package/lib/skills/now/SKILL.md +36 -0
  112. package/lib/skills/port-feature/SKILL.md +315 -0
  113. package/lib/skills/power-mode/SKILL.md +184 -0
  114. package/lib/skills/primer/SKILL.md +84 -0
  115. package/lib/skills/project-readme/SKILL.md +166 -0
  116. package/lib/skills/req-compile/SKILL.md +131 -0
  117. package/lib/skills/req-create/SKILL.md +124 -0
  118. package/lib/skills/req-extract-decisions/SKILL.md +241 -0
  119. package/lib/skills/req-finalize/SKILL.md +251 -0
  120. package/lib/skills/req-retire/SKILL.md +185 -0
  121. package/lib/skills/req-update/SKILL.md +265 -0
  122. package/lib/skills/research/SKILL.md +250 -0
  123. package/lib/skills/research-company/SKILL.md +345 -0
  124. package/lib/skills/roadmap-add/SKILL.md +238 -0
  125. package/lib/skills/roadmap-create/SKILL.md +223 -0
  126. package/lib/skills/roadmap-next/SKILL.md +132 -0
  127. package/lib/skills/security-audit/SKILL.md +246 -0
  128. package/lib/skills/serena-config/SKILL.md +92 -0
  129. package/lib/skills/simplify/SKILL.md +227 -0
  130. package/lib/skills/tackle/SKILL.md +156 -0
  131. package/lib/skills/task-add/SKILL.md +208 -0
  132. package/lib/skills/task-audit/SKILL.md +294 -0
  133. package/lib/skills/task-trash/SKILL.md +115 -0
  134. package/lib/skills/task-update/SKILL.md +136 -0
  135. package/lib/skills/uat-auto/SKILL.md +69 -0
  136. package/lib/skills/uat-auto-plus/SKILL.md +115 -0
  137. package/lib/skills/uat-generate/SKILL.md +289 -0
  138. package/lib/skills/uat-skip/SKILL.md +169 -0
  139. package/lib/skills/uat-walk/SKILL.md +164 -0
  140. package/lib/skills/uat-walk/UAT-CORE.md +140 -0
  141. package/lib/skills/update-docs/SKILL.md +75 -0
  142. package/lib/skills/wiki-archive/SKILL.md +96 -0
  143. package/lib/skills/wiki-ingest/SKILL.md +139 -0
  144. package/lib/skills/wiki-lint/SKILL.md +131 -0
  145. package/lib/skills/wiki-query/SKILL.md +71 -0
  146. package/lib/skills/wiki-rotate-log/SKILL.md +90 -0
  147. package/lib/skills/wiki-tidy/SKILL.md +107 -0
  148. package/package.json +32 -0
  149. package/raw/.gitkeep +0 -0
  150. package/raw/design-principles.md +65 -0
  151. package/raw/guides/command-anti-patterns.md +79 -0
  152. package/raw/guides/deployment-strategy.md +448 -0
  153. package/raw/guides/evals-framework.md +452 -0
  154. package/raw/guides/mcp-tools.md +335 -0
  155. package/raw/guides/task-spec.md +79 -0
  156. package/raw/guides/type-checking-templates/README.md +112 -0
  157. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +105 -0
  158. package/raw/guides/type-checking-templates/python/mypy.ini +69 -0
  159. package/raw/guides/type-checking-templates/python/pyproject.toml +164 -0
  160. package/raw/guides/type-checking-templates/python/pyrightconfig.json +67 -0
  161. package/raw/guides/type-checking-templates/tsconfig/tsconfig.app.jsonc +45 -0
  162. package/raw/guides/type-checking-templates/tsconfig/tsconfig.lib.jsonc +44 -0
  163. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node-esm.jsonc +40 -0
  164. package/raw/guides/type-checking-templates/tsconfig/tsconfig.node.jsonc +34 -0
  165. package/raw/guides/type-checking-templates/tsconfig/tsconfig.vite-root.json +8 -0
  166. package/raw/harness-notes.md +20 -0
  167. package/raw/house-style/components/Badge.tsx +16 -0
  168. package/raw/house-style/components/Button.tsx +32 -0
  169. package/raw/house-style/components/Card.tsx +26 -0
  170. package/raw/house-style/components/Chip.tsx +57 -0
  171. package/raw/house-style/components/IconButton.tsx +67 -0
  172. package/raw/house-style/components/Modal.tsx +18 -0
  173. package/raw/house-style/components/Stepper.tsx +141 -0
  174. package/raw/house-style/components/icons.tsx +128 -0
  175. package/raw/house-style/preview/src/index.css +46 -0
  176. package/raw/house-style/tokens/tailwind.preset.ts +49 -0
  177. package/raw/house-style/tokens/tokens.json +62 -0
  178. package/raw/llm-wiki-2.md +162 -0
  179. package/raw/llm-wiki.md +75 -0
  180. package/raw/research/dark-mode-theme/index.md +85 -0
  181. package/raw/research/dark-mode-theme/sources.md +49 -0
  182. package/raw/research/serena-mcp-disconnect/index.md +81 -0
  183. package/raw/research/serena-mcp-disconnect/sources.md +87 -0
  184. package/raw/research/wiki-tooling-improvements/index.md +126 -0
  185. package/raw/research/wiki-tooling-improvements/sources.md +73 -0
  186. package/raw/software-factory-case-study.pdf +0 -0
package/lib/README.md ADDED
@@ -0,0 +1,27 @@
1
+ # lib/
2
+
3
+ This is the asset library packaged and shipped by `@codewizard-dt/bootstrap` (see the `files` field in `../package.json`). Nothing here runs standalone — `bin/cli.js` dispatches `bootstrap <command>` to a script in `lib/scripts/`, and that script copies, syncs, or generates the other three folders into a target project or into global Claude Code state (`~/.claude/`).
4
+
5
+ ```
6
+ lib/
7
+ ├── hooks/ Node.js PreToolUse/PostToolUse/SessionStart hook scripts — safety + Serena-first enforcement
8
+ ├── scripts/ Bash orchestration — the only entry points invoked by bin/cli.js
9
+ ├── prompts/ Markdown prompts fed to the `claude` CLI for context-sensitive scaffolding
10
+ └── skills/ SKILL.md slash-command definitions — the reusable agent workflow library
11
+ ```
12
+
13
+ | Folder | What it is | Installed to |
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`) |
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
+ | [`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
+ | [`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`) |
19
+
20
+ ## How the pieces fit together
21
+
22
+ 1. A user runs `npx @codewizard-dt/bootstrap <command>` (or the installed `bootstrap` bin).
23
+ 2. `bin/cli.js` resolves the command to a script in `lib/scripts/` and execs it with the target project path.
24
+ 3. That script sources `lib/scripts/lib.sh` for shared helpers, then does some combination of: installing MCP servers, `rsync`-ing `lib/skills/` and `lib/hooks/` to `~/.claude/`, scaffolding `wiki/`/`raw/` from `lib/scripts/templates/wiki/`, assembling `.docs/guides/mcp-tools.md` from `lib/scripts/templates/guides/stubs/`, and/or invoking `claude --print` with a prompt from `lib/prompts/` for anything that needs project-specific judgment (CI/CD scaffolding, `.docs/`→wiki migration, strict type-check setup).
25
+ 4. Once installed, the target project's Claude Code sessions pick up the copied hooks (enforcement) and skills (slash commands) automatically; the wiki scaffold and `CLAUDE.md` additions give those sessions durable, file-system-backed state.
26
+
27
+ See the root [`README.md`](../README.md) for the full architecture diagram and component descriptions; this file and its children document `lib/` at the file level.
@@ -0,0 +1,316 @@
1
+ # Hooks
2
+
3
+ PreToolUse / PostToolUse / SessionStart hook scripts managed by this template.
4
+ `./lib/scripts/install-global.sh` (also `npx @codewizard-dt/bootstrap install`)
5
+ rsyncs this directory — including `lib/` — to `~/.claude/hooks/`.
6
+
7
+ **Important:** the install script copies the *scripts* but does **not** wire them
8
+ into `~/.claude/settings.json`. Hook *registration* is a global-settings concern
9
+ and must be added once, by hand, using the snippets below. Without the wiring the
10
+ scripts sit on disk and never run.
11
+
12
+ ## Why hooks (vs. allow/deny permission rules)
13
+
14
+ The permissions `deny` list is **not consulted** when an agent runs in
15
+ `bypassPermissions` mode (`--dangerously-skip-permissions`, power-mode teammates,
16
+ or any subagent spawned with `mode: bypassPermissions`). `PreToolUse` hooks, by
17
+ contrast, fire in **every** permission mode and for **subagent** tool calls. So a
18
+ hook is the only reliable enforcement point for "this must never run, even under
19
+ bypass." Keep a matching `deny` entry too — belt-and-suspenders for normal modes.
20
+
21
+ ---
22
+
23
+ ## Scripts
24
+
25
+ ### Safety / policy hooks
26
+
27
+ | Script | Matcher | Blocks |
28
+ |--------|---------|--------|
29
+ | `env-file-guard.js` | `Read\|Write\|Edit\|MultiEdit` | Reading or writing any `.env` file (`.env`, `.env.local`, etc.) — `.env.example` is allowed |
30
+ | `mv-absolute-path-block.js` | `Bash` (`if: Bash(mv *)`) | `mv` to an absolute path outside the project root |
31
+ | `git-protected-ops-block.js` | `Bash` (no `if:`) | `git stash` / `git restore` / `git checkout` in any command segment |
32
+
33
+ ### Serena-first enforcement hooks (ported from `claude-code-lsp-enforcement-kit`)
34
+
35
+ These hooks enforce Serena as the primary tool for code navigation and editing.
36
+ They are sourced from `claude-code-lsp-enforcement-kit` — this is the single
37
+ source of truth; changes here propagate on the next `install-global.sh` run.
38
+
39
+ | Script | Event / Matcher | Purpose |
40
+ |--------|-----------------|---------|
41
+ | `serena-bash-grep-block.js` | `PreToolUse` / `Bash` | Blocks `grep`/`rg` on code symbols, `cat`/`head`/`tail` on code files, `ls`/`find`/`tree` on code dirs, `sed -i`/`awk -i`/`perl -i` in-place edits. Suggests Serena equivalents. |
42
+ | `serena-first-guard.js` | `PreToolUse` / `Grep` | Blocks the built-in Grep tool when the pattern contains a code symbol (camelCase, PascalCase, snake_case_fn). |
43
+ | `serena-first-glob-guard.js` | `PreToolUse` / `Glob` | Blocks Glob patterns that encode a code symbol name (use `find_symbol` instead). |
44
+ | `serena-first-read-guard.js` | `PreToolUse` / `Read` | Gate-based Read guard: requires Serena warmup before code Reads; warns/blocks on excessive Reads without Serena navigation. |
45
+ | `serena-edit-guard.js` | `PreToolUse` / `Edit\|MultiEdit` | Hard-blocks Edit / MultiEdit on code files; directs to `replace_symbol_body` / `replace_content`. |
46
+ | `serena-write-guard.js` | `PreToolUse` / `Write` | Hard-blocks Write on *existing* code files; new files pass through (no symbols to preserve). |
47
+ | `serena-pre-delegation.js` | `PreToolUse` / `Agent` | Warns/blocks implement-phase Agent spawns that lack `## LSP CONTEXT` in their prompt. |
48
+ | `serena-usage-tracker.js` | `PostToolUse` + `PostToolUseFailure` / Serena tools | Tracks successful Serena calls in `~/.claude/state/lsp-ready-<hash>` for the read-guard gate decisions, **and** drives health tracking / fail-open enforcement (see below). |
49
+ | `serena-session-reset.js` | `SessionStart` | Wipes stale Serena nav state at session start so "surgical mode" doesn't carry over across sessions. |
50
+
51
+ `git-protected-ops-block.js` is wired **without** an `if:` filter on purpose: it
52
+ does its own matching in JS (splitting on `;`, `&&`, `||`, `|` and handling
53
+ `git -C …`, `--no-pager`, etc.), so enforcement never depends on the same
54
+ permission-matcher path that lets compound/piped commands slip past a `deny` rule.
55
+
56
+ ### Health tracking & fail-open enforcement
57
+
58
+ The Serena guards block Grep/Read/Edit/Write/Bash and demand Serena tools. If the
59
+ Serena MCP server crashes or hangs, that would trap the agent between broken
60
+ Serena calls and blocked fallbacks. To prevent this, enforcement is **fail-open**:
61
+
62
+ - **Scoped to the project root — out-of-project paths always pass.** Serena is
63
+ registered per-project and can only operate on files inside the project root,
64
+ so any tool call whose target path resolves *outside* the root passes through
65
+ untouched: Read/Edit/Write on an out-of-project `file_path`, Grep/Glob with a
66
+ `path` param outside the root, and Bash read/exploration commands
67
+ (`ls`/`find`/`cat`/`grep` …) whose every path target is an absolute or `~`
68
+ path outside the root — or an unresolvable shell-variable path like
69
+ `ls "$SDIR"` (Serena-first is agent guidance, not a security boundary, so a
70
+ path that can't be proven in-project is allowed for reads). In-place edits
71
+ (`sed -i` etc.) with variable paths remain blocked as before; out-of-project
72
+ absolute edit paths pass (Serena can't reach them anyway). `isOutsideProject()`
73
+ in `lib/serena.js` is the shared resolver (`~`/relative expansion + a
74
+ trailing-separator containment check).
75
+ - **Assumed healthy by default.** Every guard reads the per-project state file
76
+ (`~/.claude/state/lsp-ready-<md5(cwd)>`) and enforces unless it finds
77
+ `health.should_enforce === false`. A missing file, legacy file without a
78
+ `health` field, or 24h-expired file all mean *enforce* (assume healthy). The
79
+ cost is one small JSON stat+read per guarded call.
80
+ - **Failures drive the decision.** `serena-usage-tracker.js` sees every Serena
81
+ call outcome (success **and** failure) and classifies failures:
82
+ - *tool-level* (e.g. "symbol not found", "no results", or a benign decline
83
+ like "cannot extract symbols" for a file type not enabled in
84
+ `.serena/project.yml`) — the server answered, the query just missed or was
85
+ declined for an expected reason. Record the error, **keep enforcing**. An
86
+ unrecognized error string also defaults here — a hook only runs because
87
+ the MCP round-trip completed with a payload to classify, which already
88
+ proves the server responded.
89
+ - *transport-level* (timeout / connection closed / broken pipe / a genuinely
90
+ empty payload) — probe the OS for a Serena process bound to this
91
+ project's `--project` path, **diagnostically only** (the process is never
92
+ terminated: a live process that just answered, even with an error, has
93
+ already proven it isn't hung, and there is no documented way to
94
+ reconnect a stdio MCP server mid-session — killing it has no realistic
95
+ upside and a confirmed downside). If a live process remains, keep
96
+ enforcing, just record the error; if none remains, write
97
+ `health.should_enforce = false` and emit a **one-time** `systemMessage`
98
+ notice that Serena-first enforcement is disabled for the session.
99
+ - **Auto-recovery.** The next **successful** Serena call restores
100
+ `health` to enforcing/healthy (and re-arms the one-time notice), so enforcement
101
+ comes back automatically once Serena reconnects or the session restarts
102
+ (`serena-session-reset.js` wipes the file at SessionStart).
103
+ - **Gate 1 deadlock backstop.** `serena-first-read-guard.js` tracks
104
+ `warmup_block_count` — consecutive Gate 1 blocks with no successful Serena
105
+ call in between. If it reaches 3 (an unforeseen error type evaded the
106
+ classification above, or Serena never gets a call attempted at all), the
107
+ guard escalates to the same circuit breaker — `health.should_enforce =
108
+ false` plus a one-time notice — rather than blocking indefinitely. It
109
+ escalates the shared flag, not just this one guard, so the deadlock can't
110
+ simply relocate to the next guard hook. Resets to 0 on the next successful
111
+ Serena call, same as the rest of `health`.
112
+
113
+ **Version compatibility.** `PostToolUseFailure` fires on failed tool calls
114
+ (including MCP tools, in every permission mode) but is a newer event; its `error`
115
+ payload is undocumented and handled defensively. On Claude Code builds without
116
+ `PostToolUseFailure`, failed Serena calls still reach the same script via the
117
+ `PostToolUse` error-shaped `tool_response` — so the wiring registers
118
+ `serena-usage-tracker.js` on **both** events with the same matcher, and either
119
+ path produces the same health outcome. There is no documented way to reconnect a
120
+ stdio MCP server mid-session, so the process is never killed on the theory that
121
+ the host might respawn it — fail-open + auto-recovery (or the Gate 1 backstop,
122
+ as a last resort) is the only guaranteed path back to a working session.
123
+
124
+ ### Shared library
125
+
126
+ | File | Used by |
127
+ |------|---------|
128
+ | `lib/serena.js` | All Serena hooks — intent→tool mapping, `isAllowedPath`, block-message builders, per-project state file (`getStateFilePath`/`readStateFile`/`writeStateFile`/`shouldEnforceSerena`/`defaultFlag`/`defaultHealth`), an advisory lock + atomic read-modify-write helper (`acquireLock`/`releaseLock`/`updateStateFile`) used by every hook that writes the state file, failure classification + process health (`classifySerenaFailure`/`isSerenaProcessAlive` — diagnostic only, never terminates the process), and consolidated symbol detection (`isCodeSymbol`/`extractSymbolsFromPattern`) |
129
+ | `lib/serena-languages.js` | `lib/serena.js` — reads `.serena/project.yml` to scope enforcement to configured languages |
130
+
131
+ ### State file JSON schema
132
+
133
+ One file per project cwd, `~/.claude/state/lsp-ready-<md5(cwd).slice(0,12)>`,
134
+ written via `updateStateFile()` (locked, atomic) by `serena-usage-tracker.js`
135
+ and `serena-first-read-guard.js`:
136
+
137
+ ```jsonc
138
+ {
139
+ "cwd": "/path/to/project",
140
+ "warmup_done": false, // Gate 1: has a Serena nav call ever succeeded this session?
141
+ "nav_count": 0, // successful nav calls since warmup (Gates 4/5)
142
+ "read_count": 0, // len(read_files)
143
+ "read_files": [], // code files already Read this session
144
+ "warmup_block_count": 0, // consecutive Gate 1 blocks — resets on any success, see backstop above
145
+ "cold_start_retries": 0,
146
+ "timestamp": 0, // last write; entries older than 24h are treated as missing
147
+ "last_tool": "",
148
+ "health": {
149
+ "should_enforce": true, // false ⇒ every guard fails open for this project
150
+ "healthy": true,
151
+ "error_count": 0,
152
+ "last_error": null,
153
+ "last_check": 0,
154
+ "notified": false // one-time systemMessage already shown for this outage
155
+ }
156
+ }
157
+ ```
158
+
159
+ A sibling `<path>.lock` file exists only transiently, for the duration of a
160
+ single read-modify-write cycle (a few ms). It self-heals: a lock older than
161
+ 750ms is treated as orphaned (its holder crashed) and is cleared by the next
162
+ acquirer rather than blocking on it.
163
+
164
+ ---
165
+
166
+ ## Required `~/.claude/settings.json` wiring
167
+
168
+ Add these under `hooks`. If a block already exists for a given matcher, add the
169
+ hook objects to its existing `hooks` array rather than creating a second block.
170
+
171
+ ```json
172
+ {
173
+ "hooks": {
174
+ "SessionStart": [
175
+ {
176
+ "hooks": [
177
+ {
178
+ "type": "command",
179
+ "command": "node ~/.claude/hooks/serena-session-reset.js"
180
+ }
181
+ ]
182
+ }
183
+ ],
184
+ "PreToolUse": [
185
+ {
186
+ "matcher": "Read|Write|Edit|MultiEdit",
187
+ "hooks": [
188
+ {
189
+ "type": "command",
190
+ "command": "node ~/.claude/hooks/env-file-guard.js"
191
+ }
192
+ ]
193
+ },
194
+ {
195
+ "matcher": "Read",
196
+ "hooks": [
197
+ {
198
+ "type": "command",
199
+ "command": "node ~/.claude/hooks/serena-first-read-guard.js"
200
+ }
201
+ ]
202
+ },
203
+ {
204
+ "matcher": "Edit|MultiEdit",
205
+ "hooks": [
206
+ {
207
+ "type": "command",
208
+ "command": "node ~/.claude/hooks/serena-edit-guard.js"
209
+ }
210
+ ]
211
+ },
212
+ {
213
+ "matcher": "Write",
214
+ "hooks": [
215
+ {
216
+ "type": "command",
217
+ "command": "node ~/.claude/hooks/serena-write-guard.js"
218
+ }
219
+ ]
220
+ },
221
+ {
222
+ "matcher": "Grep",
223
+ "hooks": [
224
+ {
225
+ "type": "command",
226
+ "command": "node ~/.claude/hooks/serena-first-guard.js"
227
+ }
228
+ ]
229
+ },
230
+ {
231
+ "matcher": "Glob",
232
+ "hooks": [
233
+ {
234
+ "type": "command",
235
+ "command": "node ~/.claude/hooks/serena-first-glob-guard.js"
236
+ }
237
+ ]
238
+ },
239
+ {
240
+ "matcher": "Agent",
241
+ "hooks": [
242
+ {
243
+ "type": "command",
244
+ "command": "node ~/.claude/hooks/serena-pre-delegation.js"
245
+ }
246
+ ]
247
+ },
248
+ {
249
+ "matcher": "Bash",
250
+ "hooks": [
251
+ {
252
+ "type": "command",
253
+ "command": "node ~/.claude/hooks/serena-bash-grep-block.js"
254
+ },
255
+ {
256
+ "type": "command",
257
+ "command": "node ~/.claude/hooks/mv-absolute-path-block.js",
258
+ "if": "Bash(mv *)"
259
+ },
260
+ {
261
+ "type": "command",
262
+ "command": "node ~/.claude/hooks/git-protected-ops-block.js"
263
+ }
264
+ ]
265
+ }
266
+ ],
267
+ "PostToolUse": [
268
+ {
269
+ "matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
270
+ "hooks": [
271
+ {
272
+ "type": "command",
273
+ "command": "node ~/.claude/hooks/serena-usage-tracker.js"
274
+ }
275
+ ]
276
+ }
277
+ ],
278
+ "PostToolUseFailure": [
279
+ {
280
+ "matcher": "mcp__serena__.*|mcp__plugin_[^_]+_serena__.*",
281
+ "hooks": [
282
+ {
283
+ "type": "command",
284
+ "command": "node ~/.claude/hooks/serena-usage-tracker.js"
285
+ }
286
+ ]
287
+ }
288
+ ]
289
+ }
290
+ }
291
+ ```
292
+
293
+ The `PostToolUse` matcher is broadened from the six navigation tools to **all**
294
+ Serena tools so every call feeds health tracking; the tracker gates the read-guard
295
+ nav counters internally (only the six nav/exploration tools advance the gate, as
296
+ before). The `PostToolUseFailure` block points at the same script — see
297
+ [Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)
298
+ for why both events are wired. If your Claude Code build does not support
299
+ `PostToolUseFailure`, that block is simply ignored and the `PostToolUse` error
300
+ path still catches failures.
301
+
302
+ Recommended companion `deny` entries (belt-and-suspenders for normal modes):
303
+
304
+ ```json
305
+ {
306
+ "permissions": {
307
+ "deny": [
308
+ "Bash(git stash:*)",
309
+ "Bash(git restore:*)",
310
+ "Bash(git checkout:*)"
311
+ ]
312
+ }
313
+ }
314
+ ```
315
+
316
+ Hooks load at session start, so restart any running session after wiring.
@@ -0,0 +1,45 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ const path = require('path');
5
+
6
+ function isBlockedEnvFile(filePath) {
7
+ if (!filePath) return false;
8
+ const basename = path.basename(String(filePath));
9
+ // Block .env exactly, and .env.* variants (e.g. .env.local, .env.production)
10
+ // Allow .env.example — the one permitted exception
11
+ return basename === '.env' ||
12
+ (basename.startsWith('.env.') && basename !== '.env.example');
13
+ }
14
+
15
+ let raw = '';
16
+ process.stdin.setEncoding('utf8');
17
+ process.stdin.on('data', d => { raw += d; });
18
+ process.stdin.on('end', () => {
19
+ let data;
20
+ try { data = JSON.parse(raw); } catch { process.exit(0); }
21
+
22
+ const { tool_name, tool_input } = data;
23
+ let blocked = null;
24
+
25
+ if (['Read', 'Write', 'Edit'].includes(tool_name)) {
26
+ const fp = tool_input?.file_path;
27
+ if (isBlockedEnvFile(fp)) blocked = fp;
28
+ } else if (tool_name === 'MultiEdit') {
29
+ const edits = Array.isArray(tool_input?.edits) ? tool_input.edits : [];
30
+ const bad = edits.find(e => isBlockedEnvFile(e?.file_path));
31
+ if (bad) blocked = bad.file_path;
32
+ }
33
+
34
+ if (blocked) {
35
+ process.stdout.write(JSON.stringify({
36
+ hookSpecificOutput: {
37
+ hookEventName: 'PreToolUse',
38
+ permissionDecision: 'deny',
39
+ permissionDecisionReason: `.env policy: "${blocked}" cannot be read or written. Only .env.example is permitted. You may source an .env file in a Bash command to use its variables.`
40
+ }
41
+ }) + '\n');
42
+ }
43
+
44
+ process.exit(0);
45
+ });
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // git-protected-ops-block.js — PreToolUse hook (matcher: Bash)
5
+ //
6
+ // Hard-blocks `git stash`, `git restore`, and `git checkout` (and their
7
+ // subcommands, e.g. `git stash pop`) in ANY segment of a Bash command.
8
+ //
9
+ // Why a hook and not a deny rule: the permissions allow/deny engine is
10
+ // short-circuited under bypassPermissions mode (power-mode teammates,
11
+ // --dangerously-skip-permissions). PreToolUse hooks fire regardless of
12
+ // permission mode and for subagent tool calls, so this is the only
13
+ // enforcement point that reliably stops these commands everywhere.
14
+ //
15
+ // Matching is done in JS (not via the hook `if:` filter) so it never depends
16
+ // on the same matcher path that lets compound/piped commands slip through.
17
+
18
+ const BLOCKED_SUBCOMMANDS = new Set(['stash', 'restore', 'checkout']);
19
+
20
+ // `git` pre-subcommand options that consume the FOLLOWING token as their value.
21
+ // We skip both so we land on the real subcommand (e.g. `git -C /repo stash`).
22
+ const VALUE_OPTIONS = new Set(['-C', '-c', '--namespace', '--git-dir', '--work-tree', '--exec-path']);
23
+
24
+ let raw = '';
25
+ process.stdin.setEncoding('utf8');
26
+ process.stdin.on('data', d => { raw += d; });
27
+ process.stdin.on('end', () => {
28
+ let data;
29
+ try { data = JSON.parse(raw); } catch { process.exit(0); }
30
+ if (data.tool_name !== 'Bash') process.exit(0);
31
+
32
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
33
+ if (!fullCmd) process.exit(0);
34
+
35
+ // Split on command separators AND pipes, inspecting each segment alone so a
36
+ // blocked command can't hide behind `&&`, `;`, `||`, or `| tail -20`.
37
+ const segments = fullCmd.split(/;|&&|\|\||\|/).map(s => s.trim()).filter(Boolean);
38
+
39
+ for (const segment of segments) {
40
+ const tokens = segment.split(/\s+/);
41
+ const gitIdx = tokens.findIndex(t => t === 'git');
42
+ if (gitIdx === -1) continue;
43
+
44
+ // Walk tokens after `git`, skipping global options (and the values of
45
+ // options that take one) to find the actual subcommand.
46
+ let i = gitIdx + 1;
47
+ let subcommand = null;
48
+ while (i < tokens.length) {
49
+ const tok = tokens[i];
50
+ if (tok.startsWith('-')) {
51
+ // `-C /path` / `-c k=v` style: skip the value token too, unless it's
52
+ // an `--opt=value` form (self-contained).
53
+ if (VALUE_OPTIONS.has(tok)) i += 1;
54
+ i += 1;
55
+ continue;
56
+ }
57
+ subcommand = tok;
58
+ break;
59
+ }
60
+
61
+ if (subcommand && BLOCKED_SUBCOMMANDS.has(subcommand)) {
62
+ console.log(JSON.stringify({
63
+ hookSpecificOutput: {
64
+ hookEventName: 'PreToolUse',
65
+ permissionDecision: 'deny',
66
+ permissionDecisionReason:
67
+ `Blocked: \`git ${subcommand}\` is disabled in this environment because it can ` +
68
+ `silently discard or hide uncommitted work. This block is enforced even under ` +
69
+ `bypassed permissions. If you need to set work aside, ask the user.`,
70
+ },
71
+ }));
72
+ process.exit(0);
73
+ }
74
+ }
75
+
76
+ process.exit(0);
77
+ });
@@ -0,0 +1,158 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * serena-languages.js — reads project/global Serena config for enabled languages
5
+ * and maps them to file extensions for use in enforcement hooks.
6
+ *
7
+ * Resolution order (mirrors Serena itself):
8
+ * 1. ~/.serena/serena_config.yml — global defaults
9
+ * 2. {cwd}/.serena/project.yml — project override (wins when languages: present)
10
+ *
11
+ * Both inline and block YAML list forms are handled:
12
+ * languages: []
13
+ * languages: [typescript, python]
14
+ * languages:
15
+ * - typescript
16
+ * - python
17
+ */
18
+
19
+ const fs = require('fs');
20
+ const path = require('path');
21
+ const os = require('os');
22
+
23
+ const GLOBAL_CONFIG = path.join(os.homedir(), '.serena', 'serena_config.yml');
24
+
25
+ // Serena language name → file extensions (lowercase, no leading dot)
26
+ const LANG_EXTS = {
27
+ typescript: ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs'],
28
+ python: ['py'],
29
+ python_jedi: ['py'],
30
+ python_ty: ['py'],
31
+ go: ['go'],
32
+ rust: ['rs'],
33
+ java: ['java'],
34
+ kotlin: ['kt', 'kts'],
35
+ swift: ['swift'],
36
+ vue: ['vue'],
37
+ svelte: ['svelte'],
38
+ cpp: ['cpp', 'cc', 'cxx', 'c', 'h', 'hpp'],
39
+ cpp_ccls: ['cpp', 'cc', 'cxx', 'c', 'h', 'hpp'],
40
+ csharp: ['cs'],
41
+ csharp_omnisharp: ['cs'],
42
+ ruby: ['rb'],
43
+ ruby_solargraph: ['rb'],
44
+ php: ['php'],
45
+ php_phpactor: ['php'],
46
+ scala: ['scala'],
47
+ bash: ['sh', 'bash'],
48
+ markdown: ['md', 'mdx'],
49
+ yaml: ['yml', 'yaml'],
50
+ json: ['json', 'jsonc'],
51
+ lua: ['lua'],
52
+ luau: ['lua'],
53
+ elixir: ['ex', 'exs'],
54
+ erlang: ['erl', 'hrl'],
55
+ haskell: ['hs', 'lhs'],
56
+ dart: ['dart'],
57
+ r: ['r'],
58
+ clojure: ['clj', 'cljs', 'cljc'],
59
+ ocaml: ['ml', 'mli'],
60
+ perl: ['pl', 'pm'],
61
+ powershell: ['ps1', 'psm1'],
62
+ groovy: ['groovy'],
63
+ nix: ['nix'],
64
+ julia: ['jl'],
65
+ zig: ['zig'],
66
+ terraform: ['tf', 'tfvars'],
67
+ toml: ['toml'],
68
+ solidity: ['sol'],
69
+ pascal: ['pas', 'pp'],
70
+ elm: ['elm'],
71
+ crystal: ['cr'],
72
+ fortran: ['f', 'f90', 'f95', 'for'],
73
+ fsharp: ['fs', 'fsi', 'fsx'],
74
+ lean4: ['lean'],
75
+ al: ['al'],
76
+ hlsl: ['hlsl'],
77
+ msl: ['metal'],
78
+ matlab: ['m'],
79
+ rego: ['rego'],
80
+ systemverilog: ['sv', 'svh'],
81
+ haxe: ['hx'],
82
+ scss: ['scss', 'sass', 'css'],
83
+ sass: ['scss', 'sass', 'css'],
84
+ css: ['css', 'scss', 'sass'],
85
+ };
86
+
87
+ /**
88
+ * Parse the `languages:` list from a YAML string (no external YAML parser).
89
+ *
90
+ * Returns null when the key is absent.
91
+ * Returns [] when the key is present but the list is empty.
92
+ * Returns [...] for a populated list (inline or block form).
93
+ */
94
+ function parseLanguagesFromYaml(content) {
95
+ if (!content) return null;
96
+
97
+ // Inline list: languages: [] or languages: [typescript, python]
98
+ const inlineMatch = content.match(/^languages\s*:\s*\[([^\]]*)\]/m);
99
+ if (inlineMatch) {
100
+ const inner = inlineMatch[1].trim();
101
+ if (!inner) return [];
102
+ return inner.split(',').map(s => s.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
103
+ }
104
+
105
+ // Key present but no inline bracket → look for block list items on following lines
106
+ const keyMatch = content.match(/^languages\s*:/m);
107
+ if (!keyMatch) return null;
108
+
109
+ const afterKey = content.slice(content.indexOf(keyMatch[0]) + keyMatch[0].length);
110
+ const items = [];
111
+ for (const line of afterKey.split('\n')) {
112
+ if (/^\s*#/.test(line)) continue; // skip comment lines
113
+ if (/^[a-zA-Z]/.test(line)) break; // next top-level key — stop
114
+ const m = line.match(/^\s*-\s*(['"]?)(\S+)\1/);
115
+ if (m) items.push(m[2]);
116
+ }
117
+ return items;
118
+ }
119
+
120
+ function readFileSafe(filePath) {
121
+ try { return fs.readFileSync(filePath, 'utf8'); } catch { return null; }
122
+ }
123
+
124
+ /**
125
+ * Returns the list of enabled language names for the current working directory.
126
+ * Project config ({cwd}/.serena/project.yml) overrides the global config when
127
+ * it provides a non-null languages list (even an empty one).
128
+ */
129
+ function getEnabledLanguages() {
130
+ const globalLangs = parseLanguagesFromYaml(readFileSafe(GLOBAL_CONFIG));
131
+ const projectYml = path.join(process.cwd(), '.serena', 'project.yml');
132
+ const projectLangs = parseLanguagesFromYaml(readFileSafe(projectYml));
133
+ return (projectLangs !== null ? projectLangs : globalLangs) || [];
134
+ }
135
+
136
+ /**
137
+ * Returns a Set of file extensions (lowercase, no leading dot) for all
138
+ * enabled languages in the current project.
139
+ */
140
+ function getEnabledExtensionsSet() {
141
+ const exts = new Set();
142
+ for (const lang of getEnabledLanguages()) {
143
+ for (const ext of (LANG_EXTS[lang] || [])) exts.add(ext);
144
+ }
145
+ return exts;
146
+ }
147
+
148
+ /**
149
+ * Returns a RegExp matching file paths whose extension belongs to an enabled
150
+ * language, or null when no languages are configured.
151
+ */
152
+ function buildCodeExtensionsRegex() {
153
+ const exts = getEnabledExtensionsSet();
154
+ if (exts.size === 0) return null;
155
+ return new RegExp('\\.(' + [...exts].join('|') + ')$', 'i');
156
+ }
157
+
158
+ module.exports = { LANG_EXTS, getEnabledLanguages, getEnabledExtensionsSet, buildCodeExtensionsRegex };