@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
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // mv-absolute-path-block.js — PreToolUse hook (matcher: Bash, if: Bash(mv *))
5
+ // Blocks `mv` commands where any argument is an absolute path rooted outside
6
+ // the project directory. Directs the user to check the project root.
7
+
8
+ const path = require('path');
9
+
10
+ let raw = '';
11
+ process.stdin.setEncoding('utf8');
12
+ process.stdin.on('data', d => { raw += d; });
13
+ process.stdin.on('end', () => {
14
+ let data;
15
+ try { data = JSON.parse(raw); } catch { process.exit(0); }
16
+ if (data.tool_name !== 'Bash') process.exit(0);
17
+
18
+ const fullCmd = String(data.tool_input?.command ?? '').trim();
19
+ if (!fullCmd) process.exit(0);
20
+
21
+ const cwd = process.cwd();
22
+ const cwdWithSep = cwd + path.sep;
23
+
24
+ // Split on command separators and inspect each segment independently.
25
+ const segments = fullCmd.split(/;|&&|\|\|/).map(s => s.trim()).filter(Boolean);
26
+
27
+ for (const segment of segments) {
28
+ const tokens = segment.split(/\s+/);
29
+ const mvIdx = tokens.findIndex(t => t === 'mv');
30
+ if (mvIdx === -1) continue;
31
+
32
+ // Arguments after 'mv', skipping flags (-n, -f, -v, etc.)
33
+ const args = tokens.slice(mvIdx + 1).filter(t => !t.startsWith('-'));
34
+
35
+ const offendingArg = args.find(arg => {
36
+ return arg.startsWith('/') && arg !== cwd && !arg.startsWith(cwdWithSep)
37
+ });
38
+
39
+ if (offendingArg) {
40
+ console.log(JSON.stringify({
41
+ hookSpecificOutput: {
42
+ hookEventName: 'PreToolUse',
43
+ permissionDecision: 'deny',
44
+ permissionDecisionReason:
45
+ 'Please check that you are in the project root directory and then use a relative path instead.',
46
+ },
47
+ }));
48
+ process.exit(0);
49
+ }
50
+ }
51
+
52
+ process.exit(0);
53
+ });
@@ -0,0 +1,501 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // serena-bash-grep-block.js — PreToolUse hook (matcher: Bash)
5
+ // Blocks grep-family AND filesystem-exploration AND in-place-editing shell commands when targeting code.
6
+ // Suggests the equivalent Serena tool call.
7
+ // Pipe-grep bypass (inverse denylist): allow grep after any pipe UNLESS the first segment itself
8
+ // contains grep/rg/ag/ack, or reads a code file directly (cat/head/tail on *.ts etc., find <code-dir>).
9
+ // Container bypass: docker exec (or ssh + docker exec) bypasses all FS checks — Serena can't see inside containers.
10
+
11
+ const path = require('path');
12
+ const {
13
+ buildSuggestion, buildStructuredBlockResponse, buildBashFsSuggestion, isAllowedPath,
14
+ extractSymbolsFromPattern,
15
+ getStateFilePath, readStateFile, shouldEnforceSerena, isOutsideProject,
16
+ } = require('./lib/serena');
17
+
18
+ // Zero-width / formatting chars that would split tokens invisibly and
19
+ // bypass ASCII regex symbol detection.
20
+ const ZERO_WIDTH = /[\u00AD\u200B-\u200F\u2060-\u2064\uFEFF]/g;
21
+
22
+ let raw = '';
23
+ process.stdin.setEncoding('utf8');
24
+ process.stdin.on('data', d => { raw += d; });
25
+ process.stdin.on('end', () => {
26
+ let data;
27
+ try { data = JSON.parse(raw); } catch { process.exit(0); }
28
+ if (data.tool_name !== 'Bash') process.exit(0);
29
+ if (process.env.CLAUDE_MIGRATION === '1') process.exit(0);
30
+
31
+ // Fail-open: skip enforcement when Serena is unhealthy for this project.
32
+ if (!shouldEnforceSerena(readStateFile(getStateFilePath()))) process.exit(0);
33
+
34
+ // String coercion: non-string command would throw on .trim() and fail-open.
35
+ // Zero-width strip: prevents `grep\u200BUserFunc` evasion.
36
+ const fullCmd = String(data.tool_input?.command ?? '').trim().replace(ZERO_WIDTH, '');
37
+
38
+ // Container bypass: `docker exec`, `docker compose exec`, `docker-compose exec`.
39
+ // Serena cannot reach into a container's filesystem, so the FS-exploration and
40
+ // in-place-editing rules don't apply. Runs BEFORE segment splitting so inner
41
+ // `&&`/`;` inside `bash -c '...'` or `ssh host '...'` don't slice the context away.
42
+ // Intentionally NOT anchored at start — covers `ssh host 'docker exec ...'` patterns.
43
+ if (/(?:^|[\s'"])(?:sudo\s+)?(?:docker-compose|docker(?:\s+compose)?)(?:\s+-{1,2}[\w-]+(?:[ =]\S+)?)*\s+exec\b/i.test(fullCmd)) {
44
+ process.exit(0);
45
+ }
46
+
47
+ // SSH bypass: any ssh-to-remote-host invocation skips all Serena-first checks.
48
+ // Serena's LSP cannot reach a remote server, so grep/cat/sed/find against
49
+ // remote paths must be allowed. Matches `ssh host …`, `ssh user@host …`, and
50
+ // pipelines that contain ssh anywhere (e.g. `cat key | ssh host 'cmd'`).
51
+ // `\bssh\b` won't match `sshpass`; the trailing `\s+\S` ensures ssh has an arg
52
+ // so a bare word "ssh" inside a string/comment won't trigger the bypass.
53
+ if (/(?:^|[\s'"|;&])ssh\s+\S/i.test(fullCmd)) {
54
+ process.exit(0);
55
+ }
56
+
57
+ // Split the command on `;`, `&&`, `||` and evaluate each segment independently.
58
+ // This catches cases like `ls src/ && cat src/index.ts` where only one segment is bad.
59
+ const segments = fullCmd.split(/;|&&|\|\|/).map(s => s.trim()).filter(Boolean);
60
+
61
+ for (const cmd of segments) {
62
+ const blockResult = checkSegment(cmd, fullCmd);
63
+ if (blockResult) {
64
+ process.stderr.write(blockResult.stderr);
65
+ console.log(JSON.stringify(blockResult.json));
66
+ process.exit(2);
67
+ }
68
+ }
69
+
70
+ process.exit(0);
71
+ });
72
+
73
+ /**
74
+ * Inspect a single command segment for violations.
75
+ * Returns { stderr, json } if the segment should be blocked, or null to allow.
76
+ */
77
+ function checkSegment(cmd, fullCmd) {
78
+ // Strip transparent rtk proxy prefix so VCS/SSH/phase bypasses fire on the real command.
79
+ // e.g. `rtk git diff HEAD -- file.md` → `git diff HEAD -- file.md`
80
+ cmd = cmd.replace(/^rtk\s+/, '');
81
+
82
+ // Out-of-project scoping: Serena is per-project and can't reach outside the
83
+ // root, so a segment whose every path target escapes the project passes
84
+ // through. Read-exploration commands additionally allow variable-led paths
85
+ // (e.g. `ls "$SDIR"`) that can't be proven in-project; in-place edits do not.
86
+ if (segmentEscapesProject(cmd)) return null;
87
+
88
+ // VCS bypass: `git`, `gh`, `hg`, `jj`, `svn` may legitimately reference any
89
+ // path (e.g. `git diff HEAD -- foo.md`, `gh pr view`). They don't read file
90
+ // contents in the way `cat`/`sed`/`grep` do — the diff/show output is VCS
91
+ // metadata, not Serena-navigable code. Skip all Phase 2/3 checks for them.
92
+ // Phase 1 (grep) already has its own pipe-bypass for `git ... | grep`.
93
+ if (/^(?:sudo\s+)?(?:git|gh|hg|jj|svn)\b/.test(cmd)) {
94
+ // Still run Phase 1 in case of `git log | grep MySymbol` patterns within a single segment.
95
+ // (Phase 1 has its own allowlist for git-piped grep, so this is safe.)
96
+ if (!/\b(grep|rg|ag|ack)\b/i.test(cmd)) return null;
97
+ }
98
+
99
+ // ── PHASE 1: grep-family detection ────────────────────────────────────────
100
+
101
+ if (/\b(grep|rg|ag|ack)\b/i.test(cmd)) {
102
+ // Markdown exploration: grep/rg on .md files must go through Serena
103
+ // (search_for_pattern / read_file). Markdown writing stays on native Edit/Write,
104
+ // but reading & searching are Serena's job — the symbol-pattern heuristic below
105
+ // misses lowercase prose queries like "addendum|amend|update", which would
106
+ // otherwise slip past on a markdown target.
107
+ const mdTargetMatch = cmd.match(/(?:^|\s)((?:[~./\w-]+\/)?[\w.-]+\.md)\b/i);
108
+ if (mdTargetMatch) {
109
+ return buildMarkdownBlockResult(cmd, fullCmd, 'grep', mdTargetMatch[1]);
110
+ }
111
+
112
+ // Pipe-bypass (inverse denylist): allow grep after any pipe unless the first pipe segment
113
+ // itself runs grep/rg/ag/ack, or reads a code file directly (cat/head/tail <code-ext>,
114
+ // find <code-dir>). This covers composer, cargo, mvn, make, npm test, ruff, etc. without
115
+ // an ever-growing allowlist.
116
+ const _pipeSegs = cmd.split('|').map(s => s.trim());
117
+ if (_pipeSegs.length >= 2) {
118
+ const _firstSeg = _pipeSegs[0];
119
+ const _firstSegIsGrep = /\b(grep|rg|ag|ack)\b/i.test(_firstSeg);
120
+ const _firstSegReadsCode =
121
+ /\b(?:cat|head|tail|less|more|bat)\s+\S+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp)\b/i.test(_firstSeg) ||
122
+ /\bfind\s+\S*(?:src|app|components|lib|hooks|utils|services|actions)\b/i.test(_firstSeg);
123
+ if (!_firstSegIsGrep && !_firstSegReadsCode) return null;
124
+ }
125
+ if (/(?:^|[\/\\])(?:supabase[\/\\]migrations|\.task|\.claude|node_modules|knowledge-vault)(?:[\/\\]|$)/i.test(cmd)) return null;
126
+ if (/--include=?\S*\.(sql|json|txt|env|sh|css|scss|log)\b/i.test(cmd)) return null;
127
+
128
+ const cleaned = cmd.replace(/\\"/g, '"');
129
+ const patternMatch =
130
+ cleaned.match(/\b(?:grep|rg|ag|ack)\s+(?:-\S+\s+)*"([^"]+)"/i) ||
131
+ cleaned.match(/\b(?:grep|rg|ag|ack)\s+(?:-\S+\s+)*'([^']+)'/i) ||
132
+ cleaned.match(/\b(?:grep|rg|ag|ack)\s+(?:(?:-\w+\s+(?:[a-z]+\s+)?)*?)([A-Z][a-zA-Z]\w+)/);
133
+
134
+ if (!patternMatch) {
135
+ const fallbackTargetsCode =
136
+ /\bsrc[\\/]|\bapp[\\/]|components[\\/]|lib[\\/]|hooks[\\/]|utils[\\/]|services[\\/]|actions[\\/]/i.test(cmd) ||
137
+ /\.tsx?\b|\.jsx?\b/i.test(cmd);
138
+ if (fallbackTargetsCode) {
139
+ return buildFsBlockResult(cmd, fullCmd, 'grep', '<code file>');
140
+ }
141
+ }
142
+
143
+ if (patternMatch) {
144
+ const fullPattern = patternMatch[1];
145
+ // NOTE: split on BOTH `|` and `.` — splitting on dots avoids merging
146
+ // dotted expressions like `mcp.Tool` into `mcpTool` (camelCase false positive).
147
+ // Each token is stripped of zero-width chars and regex metachars before
148
+ // classification (see extractSymbolsFromPattern / isCodeSymbol in lib/serena.js).
149
+ const symbols = extractSymbolsFromPattern(fullPattern, {
150
+ splitRe: /\\?\||\./,
151
+ clean: p => p.replace(ZERO_WIDTH, '').replace(/[*+?^${}()[\]\\]/g, ''),
152
+ allowlist: 'bash',
153
+ });
154
+
155
+ // SECURITY: only allow the safe-prefix pipe bypass AFTER confirming no code symbols.
156
+ if (symbols.length === 0) {
157
+ const targetsCodeEarly =
158
+ /\bsrc[\\/]|\bapp[\\/]|components[\\/]|lib[\\/]|hooks[\\/]|utils[\\/]|services[\\/]|actions[\\/]/i.test(cmd) ||
159
+ /\.tsx?\b|\.jsx?\b/i.test(cmd);
160
+ const hasNonCodeTargetEarly = /\.(sql|json|txt|env|sh|css|scss|log|xml)\b/i.test(cmd) && !targetsCodeEarly;
161
+ if (hasNonCodeTargetEarly) return null;
162
+
163
+ const isSimplePipe = /\|/.test(cmd) && !/xargs|exec/.test(cmd);
164
+ const grepPos = cmd.search(/\b(grep|rg|ag|ack)\b/i);
165
+ const pipePos = cmd.indexOf('|');
166
+ if (isSimplePipe && pipePos !== -1 && pipePos < grepPos) {
167
+ const beforePipe = cmd.substring(0, pipePos).trim();
168
+ if (/^(git|npm|npx|pnpm|node|echo|cat\s+\S+\.(?:json|md|txt|log|ya?ml))/i.test(beforePipe) ||
169
+ /^(ls|wc|head|tail|sort|uniq)\b/i.test(beforePipe)) {
170
+ return null;
171
+ }
172
+ }
173
+ if (targetsCodeEarly) {
174
+ return buildFsBlockResult(cmd, fullCmd, 'grep', '<code file>');
175
+ }
176
+ return null;
177
+ }
178
+
179
+ const targetsCode =
180
+ /\bsrc[\\/]|\bapp[\\/]|components[\\/]|lib[\\/]|hooks[\\/]|utils[\\/]|services[\\/]|actions[\\/]/i.test(cmd) ||
181
+ /\.tsx?\b|\.jsx?\b/i.test(cmd) ||
182
+ /-t\s+(ts|tsx|js|jsx|typescript|javascript)\b/i.test(cmd) ||
183
+ /--type[= ](ts|tsx|js|jsx|typescript)\b/i.test(cmd) ||
184
+ /\bfind\b.*\b(src|app|components|lib)\b/.test(cmd) ||
185
+ /\bxargs\b.*\b(grep|rg|ag|ack)\b/i.test(cmd) ||
186
+ /-exec\s+(grep|rg|ag|ack)\b/i.test(cmd);
187
+
188
+ const hasNonCodeTarget =
189
+ /\.(sql|json|txt|env|sh|css|scss|log|xml)\b/i.test(cmd) &&
190
+ !targetsCode;
191
+
192
+ if (hasNonCodeTarget && !targetsCode) return null;
193
+
194
+ const suggestions = symbols.map(sym => {
195
+ const intent = /^[A-Z]/.test(sym) ? 'symbol_search' : 'references';
196
+ return ` ${sym}:\n${buildSuggestion(sym, intent, ' ')}`;
197
+ }).join('\n');
198
+
199
+ const displayCmd = fullCmd.length > 200 ? fullCmd.slice(0, 200) + '…' : fullCmd;
200
+ const serenaCall = buildBashFsSuggestion(cmd, ' ') ||
201
+ symbols.map(sym => {
202
+ const intent = /^[A-Z]/.test(sym) ? 'symbol_search' : 'references';
203
+ return ` ${buildSuggestion(sym, intent, '')}`;
204
+ }).join('\n');
205
+ const allowNote = 'Allowlist: any-CLI-piped grep (unless first segment is grep or reads a code file), non-code extensions, non-code paths.';
206
+ const reason = `SERENA-FIRST: Pattern contains code symbols [${symbols.join(', ')}].\n` +
207
+ `Command (truncated): ${displayCmd}\n` +
208
+ `Use instead:\n${suggestions}\n${allowNote}`;
209
+
210
+ const intent = /^[A-Z]/.test(symbols[0]) ? 'symbol_search' : 'references';
211
+ return {
212
+ stderr: `\n⛔ SERENA-FIRST: Blocked grep/rg — found ${symbols.length} code symbol(s): ${symbols.join(', ')}\n` +
213
+ `Serena is always connected. Use:\n${suggestions}\n\n`,
214
+ json: buildStructuredBlockResponse({ hook: 'serena-bash-grep-block', symbols, intent, reason }),
215
+ };
216
+ }
217
+ }
218
+
219
+ // ── PHASE 2: filesystem exploration detection ──────────────────────────────
220
+
221
+ // ls (but not `ls -d`) targeting non-exempt directory
222
+ const lsMatch = /\bls\b(?!\s+-d\b)(?:\s+[^\s|;&<>]+)/.exec(cmd);
223
+ if (lsMatch) {
224
+ // Extract directory argument (skip flags)
225
+ const afterLs = cmd.slice(cmd.indexOf('ls') + 2).trim();
226
+ const lsTarget = afterLs.replace(/^(?:-\S+\s+)*/, '').split(/\s/)[0] || '';
227
+ // Block only when the target is not in the always-exempt list
228
+ if (lsTarget && !isExemptDir(lsTarget)) {
229
+ return buildFsBlockResult(cmd, fullCmd, 'ls', lsTarget || '.');
230
+ }
231
+ }
232
+
233
+ // tree targeting non-exempt directory
234
+ // The `tree` CLI is always a standalone word: it is followed by whitespace, a flag, or
235
+ // end-of-segment. Package names like "tree-sitter" and "tree_sitter" contain additional
236
+ // word characters after "tree", so we require a non-word character (or end) after the
237
+ // match with (?!\w) in addition to the opening \b. This prevents false positives on
238
+ // identifiers like tree_sitter_javascript or tree-sitter.
239
+ const treeMatch = /\btree(?!\w)(?:\s+[^\s|;&<>]+)?/.exec(cmd);
240
+ if (treeMatch) {
241
+ const treeIdx = cmd.search(/\btree(?!\w)/);
242
+ const afterTree = cmd.slice(treeIdx + 4).trim();
243
+ const treeTarget = afterTree.replace(/^(?:-\S+\s+)*/, '').split(/\s/)[0] || '.';
244
+ if (!isExemptDir(treeTarget)) {
245
+ return buildFsBlockResult(cmd, fullCmd, 'tree', treeTarget);
246
+ }
247
+ }
248
+
249
+ // find -name/-path/-iname/-type targeting code
250
+ const findMatch = /\bfind\s+(\S+)\s+[^|;&<>]*-(?:name|path|iname|type)\b/.exec(cmd);
251
+ if (findMatch) {
252
+ const findTarget = findMatch[1];
253
+ if (!isExemptDir(findTarget)) {
254
+ return buildFsBlockResult(cmd, fullCmd, 'find', findTarget);
255
+ }
256
+ }
257
+
258
+ // cat/head/tail/less/more/bat on markdown — Serena owns markdown reading too.
259
+ const catMdMatch = /\b(?:cat|head|tail|less|more|bat)\b[^|;&<>]*?\s(\S+\.md)\b/i.exec(cmd);
260
+ if (catMdMatch) {
261
+ return buildMarkdownBlockResult(cmd, fullCmd, 'cat', catMdMatch[1]);
262
+ }
263
+
264
+ // cat/head/tail/less/more/bat on code-extension files
265
+ const catMatch = /\b(?:cat|head|tail|less|more|bat)\s+\S+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp)\b/.exec(cmd);
266
+ if (catMatch) {
267
+ const fileArg = extractFileArg(cmd, /\b(?:cat|head|tail|less|more|bat)\b/);
268
+ if (fileArg && !isAllowedPath(fileArg)) {
269
+ return buildFsBlockResult(cmd, fullCmd, 'cat', fileArg);
270
+ }
271
+ // Even if extraction failed, pattern already confirmed code extension
272
+ if (!fileArg) {
273
+ return buildFsBlockResult(cmd, fullCmd, 'cat', catMatch[0]);
274
+ }
275
+ }
276
+
277
+ // Fallback: head/tail/cat with flags put the file last (e.g. `head -85 file.ts`, `tail -f file.ts`).
278
+ // The catMatch regex above requires the file to be the first argument, so it misses these.
279
+ if (!catMatch && /\b(?:cat|head|tail|less|more|bat)\b/.test(cmd)) {
280
+ const lastToken = cmd.trim().split(/\s+/).pop() || '';
281
+ if (/\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp)$/i.test(lastToken) &&
282
+ !isAllowedPath(lastToken)) {
283
+ const verb = cmd.trim().split(/\s/)[0];
284
+ return buildFsBlockResult(cmd, fullCmd, verb, lastToken);
285
+ }
286
+ }
287
+
288
+ // sed/awk used as readers (no in-place flag) on code-extension files.
289
+ // Phase 3 catches the editing variants (sed -i, awk -i inplace); this rule
290
+ // covers `sed -n '8,14p' foo.py`, `awk '/x/' foo.py`, etc. The negative
291
+ // lookahead skips segments containing -i so we don't double-fire.
292
+ const sedAwkReadMatch = /\b(sed|awk)\b(?![^\n]*?\s-i(?:\s|$|nplace))[^\n]*?\s(\S+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp))\b/.exec(cmd);
293
+ if (sedAwkReadMatch) {
294
+ const verb = sedAwkReadMatch[1];
295
+ const fileArg = sedAwkReadMatch[2];
296
+ if (!isAllowedPath(fileArg)) {
297
+ return buildFsBlockResult(cmd, fullCmd, verb, fileArg);
298
+ }
299
+ }
300
+
301
+ // sed/awk as readers on markdown — Serena owns markdown reading.
302
+ const sedAwkMdMatch = /\b(sed|awk)\b(?![^\n]*?\s-i(?:\s|$|nplace))[^\n]*?\s(\S+\.md)\b/i.exec(cmd);
303
+ if (sedAwkMdMatch) {
304
+ return buildMarkdownBlockResult(cmd, fullCmd, sedAwkMdMatch[1], sedAwkMdMatch[2]);
305
+ }
306
+
307
+ // ── PHASE 3: in-place editing detection ───────────────────────────────────
308
+
309
+ // sed -i (any flag-order variant)
310
+ if (/\bsed\s+(?:-E\s+)?-i\b|\bsed\s+-i(?:\s+-E)?\b/.test(cmd)) {
311
+ const fileArg = extractLastPathArg(cmd);
312
+ if (!fileArg || !isAllowedPath(fileArg)) {
313
+ return buildInplaceBlockResult(cmd, fullCmd, 'sed -i', fileArg || '<path>');
314
+ }
315
+ }
316
+
317
+ // awk -i inplace
318
+ if (/\bawk\s+-i\s+inplace\b/.test(cmd)) {
319
+ const fileArg = extractLastPathArg(cmd);
320
+ if (!fileArg || !isAllowedPath(fileArg)) {
321
+ return buildInplaceBlockResult(cmd, fullCmd, 'awk -i inplace', fileArg || '<path>');
322
+ }
323
+ }
324
+
325
+ // perl -i (any combination of n/p/i flags)
326
+ if (/\bperl\s+-[npi]*i[npe]*\b/.test(cmd)) {
327
+ const fileArg = extractLastPathArg(cmd);
328
+ if (!fileArg || !isAllowedPath(fileArg)) {
329
+ return buildInplaceBlockResult(cmd, fullCmd, 'perl -i', fileArg || '<path>');
330
+ }
331
+ }
332
+
333
+ // >> <code-file> (append redirect)
334
+ const appendMatch = />>\s*(\S+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp))\b/.exec(cmd);
335
+ if (appendMatch) {
336
+ const fileArg = appendMatch[1];
337
+ if (!isAllowedPath(fileArg)) {
338
+ return buildInplaceBlockResult(cmd, fullCmd, '>>', fileArg);
339
+ }
340
+ }
341
+
342
+ // > <code-file> (overwrite redirect — not preceded by `2>`)
343
+ const overwriteMatch = /(?<!2)>\s*(\S+\.(ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|vue|svelte|cpp|c|h|hpp))\b/.exec(cmd);
344
+ if (overwriteMatch) {
345
+ const fileArg = overwriteMatch[1];
346
+ if (!isAllowedPath(fileArg)) {
347
+ return buildInplaceBlockResult(cmd, fullCmd, '>', fileArg);
348
+ }
349
+ }
350
+
351
+ return null;
352
+ }
353
+
354
+ // ── Helpers ────────────────────────────────────────────────────────────────
355
+
356
+ /** Strip surrounding quotes from a shell token. */
357
+ function stripQuotes(t) {
358
+ return String(t).replace(/^['"]+/, '').replace(/['"]+$/, '');
359
+ }
360
+
361
+ /** True if a segment performs an in-place edit / file-write (not a pure read). */
362
+ function segmentIsInPlaceEdit(cmd) {
363
+ return /\bsed\s+(?:-E\s+)?-i\b|\bsed\s+-i(?:\s+-E)?\b/.test(cmd) ||
364
+ /\bawk\s+-i\s+inplace\b/.test(cmd) ||
365
+ /\bperl\s+-[npi]*i[npe]*\b/.test(cmd) ||
366
+ /(?:^|[^0-9&])>>?\s*[^\s&|;]/.test(cmd); // > file / >> file (not 2>&1)
367
+ }
368
+
369
+ /** Extract path-looking argument tokens from a command segment. */
370
+ function extractPathTokens(cmd) {
371
+ const paths = [];
372
+ for (let t of String(cmd).split(/\s+/)) {
373
+ t = stripQuotes(t);
374
+ if (!t || t.startsWith('-')) continue; // empty or flag
375
+ if (/^[|&;<>]+$/.test(t)) continue; // shell operator
376
+ if (/^[sy][/|#,]/.test(t)) continue; // sed/awk script (s/a/b/, y/a/b/)
377
+ // Path-looking: contains a slash, or begins with ~ / $VAR.
378
+ if (/\//.test(t) || /^~/.test(t) || /^\$\{?\w/.test(t)) paths.push(t);
379
+ }
380
+ return paths;
381
+ }
382
+
383
+ /**
384
+ * True when a target path escapes the project root. Variable-led paths
385
+ * (`$VAR…`, unresolvable) count as escaping ONLY for read commands (`allowVar`),
386
+ * since Serena-first is agent guidance, not a security boundary, and we can't
387
+ * prove such a path is in-project. Absolute / `~` / relative paths are resolved.
388
+ */
389
+ function targetEscapesProject(t, opts = {}) {
390
+ const s = stripQuotes(t).trim();
391
+ if (!s) return false;
392
+ if (/^\$\{?\w/.test(s)) return !!opts.allowVar;
393
+ return isOutsideProject(s);
394
+ }
395
+
396
+ /**
397
+ * True when EVERY path target in a segment escapes the project root, so Serena
398
+ * can't operate on it and the segment should pass through. Read-exploration
399
+ * segments also permit unresolvable variable-led paths; in-place edits do not.
400
+ */
401
+ function segmentEscapesProject(cmd) {
402
+ const tokens = extractPathTokens(cmd);
403
+ if (tokens.length === 0) return false;
404
+ const allowVar = !segmentIsInPlaceEdit(cmd);
405
+ return tokens.every(t => targetEscapesProject(t, { allowVar }));
406
+ }
407
+
408
+ /** Directories that are always exempt from ls/tree/find blocking. */
409
+ function isExemptDir(dir) {
410
+ if (!dir || dir === '.') return false;
411
+ return /(?:^|[/\\])(?:\.claude|\.serena|\.task|node_modules|dist|build|\.git)(?:[/\\]|$)/i.test(dir) ||
412
+ /^\.claude|^\.serena|^\.task/.test(dir) ||
413
+ dir === 'node_modules' || dir === '.git';
414
+ }
415
+
416
+ /** Extract the file argument that follows a command verb (after any flags). */
417
+ function extractFileArg(cmd, verbRe) {
418
+ const match = verbRe.exec(cmd);
419
+ if (!match) return null;
420
+ const after = cmd.slice(match.index + match[0].length).trim();
421
+ // Skip flag tokens like -n 10
422
+ const token = after.replace(/^(?:-\S+(?:\s+\S+)?\s+)*/, '').split(/\s/)[0] || '';
423
+ return token || null;
424
+ }
425
+
426
+ /** Extract the last path-looking argument in a command (for sed/awk/perl). */
427
+ function extractLastPathArg(cmd) {
428
+ // Match last whitespace-delimited token that looks like a path (not a flag or substitution)
429
+ const tokens = cmd.split(/\s+/);
430
+ for (let i = tokens.length - 1; i >= 0; i--) {
431
+ const t = tokens[i];
432
+ if (t && !t.startsWith('-') && !t.startsWith("'") && !t.startsWith('"') &&
433
+ !/^[sg]\//.test(t) && /[./]/.test(t)) {
434
+ return t;
435
+ }
436
+ }
437
+ return null;
438
+ }
439
+
440
+ /** Build block result for filesystem exploration commands. */
441
+ function buildFsBlockResult(cmd, fullCmd, verb, targetPath) {
442
+ const displayCmd = fullCmd.length > 200 ? fullCmd.slice(0, 200) + '…' : fullCmd;
443
+ const serenaCall = buildBashFsSuggestion(cmd, ' ');
444
+ const allowNote = 'Allowlist: .docs/, .claude/, .serena/, node_modules/, .git/.';
445
+ const reason = `SERENA-FIRST: Filesystem exploration via '${verb}' on '${targetPath}' blocked.\n` +
446
+ `Command (truncated): ${displayCmd}\n` +
447
+ `Use instead:\n${serenaCall || ' mcp__serena__list_dir("' + targetPath + '")'}\n${allowNote}`;
448
+ return {
449
+ stderr: `\n⛔ SERENA-FIRST: Blocked '${verb}' on '${targetPath}' — use Serena list_dir/find_file.\n` +
450
+ `${serenaCall || ' mcp__serena__list_dir("' + targetPath + '")'}\n\n`,
451
+ json: buildStructuredBlockResponse({
452
+ hook: 'serena-bash-grep-block',
453
+ symbols: [targetPath],
454
+ intent: 'symbol_search',
455
+ reason,
456
+ }),
457
+ };
458
+ }
459
+
460
+ /** Build block result for in-place editing commands. */
461
+ function buildInplaceBlockResult(cmd, fullCmd, verb, targetPath) {
462
+ const displayCmd = fullCmd.length > 200 ? fullCmd.slice(0, 200) + '…' : fullCmd;
463
+ const serenaCall = buildBashFsSuggestion(cmd, ' ');
464
+ const allowNote = 'Allowlist: non-code extensions (.md, .json, .yaml, etc.).';
465
+ const reason = `SERENA-FIRST: In-place editing via '${verb}' on code file '${targetPath}' blocked.\n` +
466
+ `Command (truncated): ${displayCmd}\n` +
467
+ `Use instead:\n${serenaCall || ' mcp__serena__replace_content("' + targetPath + '", ...)'}\n${allowNote}`;
468
+ return {
469
+ stderr: `\n⛔ SERENA-FIRST: Blocked '${verb}' on '${targetPath}' — use Serena replace_content.\n` +
470
+ `${serenaCall || ' mcp__serena__replace_content("' + targetPath + '", ...)'}\n\n`,
471
+ json: buildStructuredBlockResponse({
472
+ hook: 'serena-bash-grep-block',
473
+ symbols: [targetPath],
474
+ intent: 'symbol_search',
475
+ reason,
476
+ }),
477
+ };
478
+ }
479
+
480
+ /** Build block result for markdown exploration (grep/cat/head/tail on .md). */
481
+ function buildMarkdownBlockResult(cmd, fullCmd, verb, targetPath) {
482
+ const displayCmd = fullCmd.length > 200 ? fullCmd.slice(0, 200) + '…' : fullCmd;
483
+ const serenaCall =
484
+ verb === 'grep'
485
+ ? ` mcp__serena__search_for_pattern(substring_pattern="<regex>", relative_path="${targetPath}")`
486
+ : ` mcp__serena__read_file("${targetPath}")`;
487
+ const allowNote = 'Markdown reading & searching belong to Serena; native Edit/Write are still allowed for markdown writes.';
488
+ const reason = `SERENA-FIRST: Markdown exploration via '${verb}' on '${targetPath}' blocked.\n` +
489
+ `Command (truncated): ${displayCmd}\n` +
490
+ `Use instead:\n${serenaCall}\n${allowNote}`;
491
+ return {
492
+ stderr: `\n⛔ SERENA-FIRST: Blocked '${verb}' on markdown file '${targetPath}'.\n` +
493
+ `${serenaCall}\n\n`,
494
+ json: buildStructuredBlockResponse({
495
+ hook: 'serena-bash-grep-block',
496
+ symbols: [targetPath],
497
+ intent: 'symbol_search',
498
+ reason,
499
+ }),
500
+ };
501
+ }
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ /**
5
+ * serena-edit-guard.js — PreToolUse hook (matcher: Edit, MultiEdit)
6
+ *
7
+ * HARD BLOCK: Edit / MultiEdit on code files.
8
+ * Directs agents to Serena's symbol-level edit tools instead.
9
+ *
10
+ * Policy:
11
+ * - Block any Edit or MultiEdit call whose file_path resolves to a code file.
12
+ * - Suggest mcp__serena__replace_symbol_body as the primary tool,
13
+ * mcp__serena__replace_content as the line-based fallback.
14
+ * - Allowed (pass-through): markdown, JSON, YAML, env, SQL, CSS, HTML,
15
+ * config files, test files, paths under .task/, .claude/, node_modules/.
16
+ * - No Serena state is read — this is a pure path-based policy gate.
17
+ */
18
+
19
+ const {
20
+ isAllowedPath, buildEditSuggestion, buildStructuredBlockResponse,
21
+ getStateFilePath, readStateFile, shouldEnforceSerena, isOutsideProject,
22
+ } = require('./lib/serena');
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 (e) { process.exit(0); }
30
+
31
+ const tool = data.tool_name;
32
+ if (tool !== 'Edit' && tool !== 'MultiEdit') process.exit(0);
33
+
34
+ // Fail-open: skip enforcement when Serena is unhealthy for this project.
35
+ if (!shouldEnforceSerena(readStateFile(getStateFilePath()))) process.exit(0);
36
+
37
+ const filePath = String(data.tool_input?.file_path ?? '').trim();
38
+ if (!filePath) process.exit(0);
39
+
40
+ // Enforcement is scoped to the project root — Serena can't reach outside it.
41
+ if (isOutsideProject(filePath)) process.exit(0);
42
+
43
+ if (isAllowedPath(filePath, { allowMarkdown: true })) process.exit(0);
44
+
45
+ // ── Build suggestion text ─────────────────────────────────────────────────
46
+ const suggestion = buildEditSuggestion(filePath);
47
+
48
+ const reason =
49
+ `SERENA-FIRST: ${tool} on a code file is blocked. ` +
50
+ `Use Serena's symbol-level edit tools instead:\n${suggestion}`;
51
+
52
+ process.stderr.write(
53
+ `\n⛔ SERENA-FIRST BLOCK [serena-edit-guard]: ${tool} on code file\n` +
54
+ `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n` +
55
+ `File: ${filePath}\n\n` +
56
+ `Primary — symbol-level edit (preferred):\n` +
57
+ ` mcp__serena__replace_symbol_body(<symbol_name>, "${filePath}")\n\n` +
58
+ `Fallback — line/content-based edit:\n` +
59
+ ` mcp__serena__replace_content("${filePath}", mode="literal", needle=..., repl=...)\n\n` +
60
+ `Edit remains allowed on: .md, .json, .yaml, .env, .sql, .css, .html,\n` +
61
+ ` config files (tsconfig, package.json, next.config.*), test files,\n` +
62
+ ` and paths under .task/, .claude/, node_modules/.\n` +
63
+ `━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\n`
64
+ );
65
+
66
+ console.log(JSON.stringify(buildStructuredBlockResponse({
67
+ hook: 'serena-edit-guard',
68
+ symbols: [],
69
+ intent: 'symbol_edit_body',
70
+ reason,
71
+ })));
72
+
73
+ process.exit(2);
74
+ });