@codewizard-dt/bootstrap 2.17.0 → 2.19.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 (39) hide show
  1. package/lib/hooks/README.md +94 -3
  2. package/lib/hooks/absolute-path-guard.js +5 -0
  3. package/lib/hooks/claude-settings-guard.js +5 -0
  4. package/lib/hooks/env-content-read-guard.js +13 -3
  5. package/lib/hooks/env-file-guard.js +42 -0
  6. package/lib/hooks/interpreter-indirection-guard.js +7 -0
  7. package/lib/hooks/lib/command-parse.js +8 -0
  8. package/lib/hooks/lib/serena-languages.js +94 -1
  9. package/lib/hooks/lib/serena.js +228 -0
  10. package/lib/hooks/mv-absolute-path-block.js +84 -3
  11. package/lib/hooks/package-install-consent.js +11 -0
  12. package/lib/hooks/protected-write-guard.js +7 -0
  13. package/lib/hooks/serena-bash-grep-block.js +507 -44
  14. package/lib/hooks/serena-first-glob-guard.js +65 -20
  15. package/lib/hooks/serena-first-guard.js +98 -2
  16. package/lib/hooks/serena-first-read-guard.js +92 -2
  17. package/lib/hooks/serena-pre-delegation.js +123 -0
  18. package/lib/hooks/serena-write-guard.js +56 -3
  19. package/lib/scripts/README.md +306 -1
  20. package/lib/scripts/bootstrap-prefs.js +734 -0
  21. package/lib/scripts/install-global.sh +188 -18
  22. package/lib/scripts/install-mcps.sh +102 -14
  23. package/lib/scripts/lib.sh +581 -11
  24. package/lib/scripts/merge-gitignore.sh +201 -15
  25. package/lib/scripts/sync-wiki-scaffold.sh +33 -4
  26. package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
  27. package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
  28. package/lib/scripts/update-project.sh +42 -9
  29. package/lib/skills/README.md +2 -1
  30. package/lib/skills/bootstrap-config/SKILL.md +154 -0
  31. package/lib/skills/git-commit/SKILL.md +89 -6
  32. package/lib/skills/research/SKILL.md +34 -3
  33. package/lib/skills/simplify/SKILL.md +1 -1
  34. package/lib/skills/uat-auto/SKILL.md +9 -4
  35. package/lib/skills/uat-auto-plus/SKILL.md +6 -6
  36. package/lib/skills/uat-generate/SKILL.md +47 -7
  37. package/lib/skills/uat-walk/UAT-CORE.md +41 -6
  38. package/lib/skills/wiki-query/SKILL.md +48 -8
  39. package/package.json +1 -1
@@ -32,6 +32,97 @@ cannot enumerate — and it can return a **message** explaining the block, which
32
32
  exiting 2 stops a call the rules would never see. Keep a matching `deny` entry
33
33
  too — defence in depth, and the rules keep working if a hook ever fails to fire.
34
34
 
35
+ ## Commenting standard
36
+
37
+ **The repo-wide "no comments" default is suspended in `lib/hooks/`, and only
38
+ here.** Everywhere else the default holds: self-documenting code, no commentary.
39
+ These files are the exception because they encode *security decisions* whose
40
+ rationale is not recoverable from the code. A regex tells you what it matches; it
41
+ cannot tell you which real command motivated it, which false positive was accepted
42
+ in exchange, or what breaks if you move the check above it. The comments are that
43
+ record — **do not "clean them up" as slop.** The exception does not extend to
44
+ `lib/scripts/`, `lib/skills/`, or `bin/`.
45
+
46
+ **Why, never what.** A comment restating a regex in English is worse than no
47
+ comment: it adds a second thing to keep in sync and answers a question nobody
48
+ had. Comment these five classes, and largely nothing else.
49
+
50
+ 1. **Why a pattern is in a list** — and what real command motivated it.
51
+ 2. **Why a threshold has its value** — `MAX_WALK = 64`, `prompt.length < 200`,
52
+ the 2-hour `.task/` mtime window, `FREE_READS` / `WARN_AT`. A bare number is
53
+ unauditable; a number with its reason can be argued with.
54
+ 3. **Known false positives, each with its escape hatch** — the deny message
55
+ usually names the escape hatch, so the comment's job is why the trade was
56
+ accepted.
57
+ 4. **Ordering dependencies** — where moving a check breaks the guard. State the
58
+ failure ("reversing these deadlocks Gate 1"), not that order matters.
59
+ 5. **Why a tempting simplification was rejected** — the refactor the next reader
60
+ will otherwise attempt, and what it costs.
61
+
62
+ **Point at this README; do not restate it.** The three groups above are
63
+ documented here in very different depth, and the inline comments take up exactly
64
+ the slack:
65
+
66
+ - **Command-class guards** already have a full per-hook section above (Blocks /
67
+ Why a hook / Why not X / Accepted consequence / Known friction / Residual risk
68
+ / Cost / Not covered). Their comments carry **none** of that argument — a
69
+ header block that ends in `See README.md § <section>`, plus inline notes only
70
+ where the prose does not reach (a specific lookahead, a fail-closed branch).
71
+ Two copies of one argument drift, and the copy in the code drifts silently.
72
+ - **Serena-first hooks** get only a one-line-purpose table row plus the shared
73
+ narrative sections. Nothing else records their heuristics, so here the inline
74
+ comments *are* the primary documentation and carry the full weight.
75
+ - **Safety / policy hooks** get a three-column table row. Same as above: comment
76
+ fully.
77
+
78
+ **Every file opens with this header block.** It is a signpost, not a second copy
79
+ of the README section:
80
+
81
+ ```js
82
+ /**
83
+ * <file>.js — <event>[ + <event>] / <matcher>
84
+ *
85
+ * Blocks: <the surface it gates, one line>
86
+ * Why a hook: <why a settings.json rule cannot express this>
87
+ * Fails: open|closed — <what happens when the check itself cannot run>
88
+ * False positives: <the known one> — escape hatch: <the rephrase that clears it>
89
+ * See README.md § <exact heading> for the full rationale.
90
+ */
91
+ ```
92
+
93
+ - The **matcher** belongs on the identity line because the wrong matcher makes a
94
+ hook silently inert (see [the wiring notes](#required-claudesettingsjson-wiring)).
95
+ A hook wired on two events lists both.
96
+ - A hook that gates nothing (`serena-usage-tracker.js`,
97
+ `serena-session-reset.js`) replaces `Blocks:` with `Does:` and may drop
98
+ `False positives:`.
99
+ - **`Fails:` is required for anything that can block a call**, because it is
100
+ never inferable from a skim and the answer is rarely the one you would guess.
101
+ The *infrastructure* fails **open** across nearly every guard: the shared
102
+ `readHookInput` in `lib/command-parse.js` wraps both the `JSON.parse` and the
103
+ handler call in `try { … } catch { process.exit(0) }`, and states fail-open as
104
+ the deliberate module-wide contract — so the five guards built on it allow the
105
+ call whenever the check itself cannot run. `env-file-guard.js` and
106
+ `mv-absolute-path-block.js` hand-roll their own stdin handlers and also fail
107
+ open. What fails **closed** is an ambiguous *match*: a construct the guard did
108
+ parse but cannot vouch for is blocked. `interpreter-indirection-guard.js` is
109
+ the sole genuinely fail-closed guard — a missing sibling file, a spawn error, a
110
+ 2s timeout, non-JSON output, a non-zero exit, or an unreadable deny list all
111
+ deny. Serena-first guards fail **open** by explicit design (see
112
+ [Health tracking & fail-open enforcement](#health-tracking--fail-open-enforcement)).
113
+ - Below the block, add free-form paragraphs only for structure the fields cannot
114
+ carry — a two-mode split, a payload-shape compatibility note. Keep the whole
115
+ header under ~30 lines; a header approaching the length of its README section
116
+ has become the duplicate this standard exists to prevent.
117
+
118
+ **The calibration target is `serena-usage-tracker.js:4-32`** (29 lines), which
119
+ predates this standard and already meets it: it names its two modes and what each
120
+ one *decides*, states the one non-obvious fact a reader cannot derive (both
121
+ PostToolUse and PostToolUseFailure payload shapes are handled, and that dual
122
+ handling is also the version-compatibility fallback), and **delegates rather than
123
+ restates** — `./lib/serena.js#isLspProviderTool` instead of a paragraph on tool-name
124
+ forms. Not one line of it describes what a line of code does. Match that.
125
+
35
126
  ---
36
127
 
37
128
  ## Scripts
@@ -463,7 +554,7 @@ extension, which `.env` is neither.
463
554
 
464
555
  **Relationship to `serena-bash-grep-block.js`.** That hook's grep phase goes
465
556
  further and *explicitly allows* `.env` targets as a "non-code extension"
466
- (`:126`, `:160`, `:189`). That is correct for its purpose — Serena-first
557
+ (`:312`, `:393`, `:454`). That is correct for its purpose — Serena-first
467
558
  navigation does not care about non-code files — and wrong for this one, and it is
468
559
  why `grep KEY .env` leaked. The two are complementary: the navigation hook decides
469
560
  where you should look for *code*, this one decides what may be *displayed*.
@@ -503,7 +594,7 @@ Closing only Bash would have moved the leak rather than sealed it:
503
594
  returns exactly the same lines.
504
595
 
505
596
  **`source .env` and `. .env` remain permitted. This is deliberate — do not "close
506
- the gap" later.** `CLAUDE.md` grants it and `env-file-guard.js:39` says so in its
597
+ the gap" later.** `CLAUDE.md` grants it and `env-file-guard.js:81` says so in its
507
598
  own deny message. Sourcing loads values into the environment and prints *nothing*;
508
599
  the leak is sourcing **plus emission** (`source .env && echo $KEY`), and the
509
600
  emission half can be written without `source` at all. Blocking `source` would
@@ -519,7 +610,7 @@ naming a *directory* that contains a `.env`; `find . -name .env -exec cat {} +`
519
610
  and `xargs cat` (the reader is not at the front of a segment); `git show
520
611
  HEAD:.env`; `docker exec … cat .env`.
521
612
 
522
- **Follow-up.** `isBlockedEnvFile` is byte-identical to `env-file-guard.js:6-13`
613
+ **Follow-up.** `isBlockedEnvFile` is byte-identical to `env-file-guard.js:48-55`
523
614
  and is annotated "change it in both places or in neither". It should be extracted
524
615
  into `lib/` so the two cannot drift; that was left undone here because it means
525
616
  editing a live shipped control for a refactor.
@@ -46,6 +46,11 @@
46
46
  // reason to reach for the absolute path here, and the path prefix is itself
47
47
  // the signal — inspecting the arguments to decide would put us back to
48
48
  // matching literal spellings, which is the failure this tier exists to escape.
49
+ //
50
+ // Fails: open — this hook reads nothing but the command string, so no check can
51
+ // be left unrun; a throw exits 0 via lib/command-parse.js. Its firing rule is
52
+ // the conservative half: an evasive spelling blocks even when the underlying
53
+ // command would have been allowed.
49
54
  // ---------------------------------------------------------------------------
50
55
 
51
56
  const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
@@ -71,6 +71,11 @@
71
71
  // replaces some unguarded path with a symlink and then writes through it is
72
72
  // caught (the target resolves into ~/.claude/), but an agent that writes a
73
73
  // script elsewhere and executes it is a Bash concern, not this hook's.
74
+ //
75
+ // Fails: open — realpathBestEffort() has no error return: when nothing along the
76
+ // ancestor chain resolves it hands back the lexical path, so a target whose real
77
+ // location could not be determined is classified on its spelling alone and can
78
+ // miss. A throw anywhere in the handler exits 0 via lib/command-parse.js.
74
79
 
75
80
  const fs = require('fs');
76
81
  const os = require('os');
@@ -32,7 +32,7 @@
32
32
  //
33
33
  // Do not "close this gap" later — it is not a gap. CLAUDE.md grants it
34
34
  // ("You are, however, allowed to source an .env file to use the variables in
35
- // the command line") and env-file-guard.js:39 says so in its own deny message.
35
+ // the command line") and env-file-guard.js:81 says so in its own deny message.
36
36
  //
37
37
  // The reasoning, so it does not have to be rediscovered: sourcing loads values
38
38
  // into the shell's environment and prints NOTHING. Nothing enters the
@@ -74,15 +74,25 @@
74
74
  // fires. Accepted for the same reason as protected-write-guard.js:50 —
75
75
  // narrowing it means inspecting quoting well enough to reimplement the
76
76
  // shell, and the cost of over-firing is one rephrase.
77
+ //
78
+ // Fails: open — a payload shape this hook does not expect falls through to allow
79
+ // (the try/catch wrapping the dispatch at the bottom of this file, and
80
+ // lib/command-parse.js's own handler catch). Ambiguous MATCHES go the other way
81
+ // and block, which is why a segment that merely quotes a blocked form fires.
77
82
 
78
83
  const path = require('path');
79
84
  const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
80
85
 
81
- // KEPT BYTE-IDENTICAL WITH env-file-guard.js:6-13. If the allow-list changes,
86
+ // KEPT BYTE-IDENTICAL WITH env-file-guard.js:48-55. If the allow-list changes,
82
87
  // change it in both places or in neither — two .env controls that disagree
83
88
  // about which files are secret is worse than one control. It also matches the
84
89
  // gitignore this repo ships (`.env`, `.env.*`, `!.env.example`), so "secret" is
85
90
  // defined the same way by the guard and by the thing that keeps it out of git.
91
+ //
92
+ // BUG-0007 tracks extracting this into lib/ so the two copies cannot drift. The
93
+ // twin now carries the same warning (env-file-guard.js:36-47), so both sides of
94
+ // the duplication point at each other and at the bug; README.md:522-525 records
95
+ // why the extraction was deferred.
86
96
  function isBlockedEnvFile(filePath) {
87
97
  if (!filePath) return false;
88
98
  const basename = path.basename(String(filePath));
@@ -262,7 +272,7 @@ function checkBash(data) {
262
272
 
263
273
  // Each `;`/`&&`/`||`/`|` segment gets its own turn, so a reader hidden after
264
274
  // a separator is still judged as a first token — the same reasoning as
265
- // absolute-path-guard.js:118.
275
+ // absolute-path-guard.js:123.
266
276
  for (const segment of splitSegments(fullCmd)) checkScope(segment, segment);
267
277
 
268
278
  // …and then, in one narrow case, the whole command as a single scope.
@@ -1,8 +1,50 @@
1
1
  #!/usr/bin/env node
2
2
  'use strict';
3
3
 
4
+ /**
5
+ * env-file-guard.js — PreToolUse / Read|Write|Edit|MultiEdit
6
+ *
7
+ * Blocks: file-tool reads and writes of any .env file, at any path in the tree.
8
+ * Why a hook: a deny rule matches one literal spelling. settings-deny.json
9
+ * carries Read entries for `.env` and `.env.local` only (:58-59), so
10
+ * `.env.production` and every future suffix would each need their own line,
11
+ * and Write/Edit/MultiEdit are not covered by them at all. The harder half is
12
+ * the `.env.example` carve-out: it is a hole INSIDE the pattern, and a deny
13
+ * list has no "except" — an allow entry does not override a deny entry. "Every
14
+ * `.env.` variant but one" is only expressible in code. A hook also returns a
15
+ * reason, and the reason is what points at the permitted alternative
16
+ * (`source .env`) — the difference between a policy and a wall people route
17
+ * around.
18
+ * Fails: open — unparseable stdin exits 0 silently at the JSON.parse catch
19
+ * below. A payload that parses but is not an object (`null`, a number) throws
20
+ * out of the `const { tool_name, tool_input } = data` destructure and exits
21
+ * non-zero, which Claude Code treats as a NON-blocking hook error: stderr is
22
+ * surfaced to the user but the tool call still proceeds. So both failure paths
23
+ * allow — one quietly, one loudly. This file predates lib/command-parse.js and
24
+ * does not use its readHookInput, so it has no handler-level catch to make the
25
+ * second path silent the way the command-class guards do.
26
+ * False positives: the test is a basename prefix, so `.env.template`,
27
+ * `.env.sample`, and even a doc named `.env.local.md` are all treated as live
28
+ * secrets — escape hatch: name the file so its basename does not begin with
29
+ * `.env.` (`env.template` and `example.env` both pass cleanly), or use the one
30
+ * permitted spelling, `.env.example`.
31
+ * See README.md § Safety / policy hooks for the full rationale.
32
+ */
33
+
4
34
  const path = require('path');
5
35
 
36
+ // KEPT BYTE-IDENTICAL WITH env-content-read-guard.js:86-98. If the allow-list
37
+ // changes, change it in both places or in neither — two .env controls that
38
+ // disagree about which files are secret is worse than one control. It also
39
+ // matches the gitignore this repo ships (`.env`, `.env.*`, `!.env.example`), so
40
+ // "secret" is defined the same way by the guard and by the thing that keeps the
41
+ // file out of git.
42
+ //
43
+ // BUG-0007 tracks extracting this into lib/ so the two copies cannot drift.
44
+ // Until it lands the duplication is load-bearing and this warning is the only
45
+ // thing holding it together — README.md:522-525 records why it was deferred
46
+ // (extraction means editing two live shipped controls for a pure refactor).
47
+ // Until now only the twin carried the warning; both sides do from here on.
6
48
  function isBlockedEnvFile(filePath) {
7
49
  if (!filePath) return false;
8
50
  const basename = path.basename(String(filePath));
@@ -20,6 +20,13 @@
20
20
  // The interpreter token is matched on its BASENAME with leading backslashes
21
21
  // stripped, so `/bin/bash -c`, `env bash -c`, and `\bash -c` are all caught
22
22
  // where a literal `bash -c` deny pattern is not.
23
+ //
24
+ // Fails: closed — every uncertain outcome denies. A sibling guard that is
25
+ // missing, times out, crashes, or answers with something that is not a decision
26
+ // envelope blocks; a deny list that cannot be read blocks; a payload that cannot
27
+ // be isolated blocks. The one exception sits upstream of this file: a hook
28
+ // payload that is not parseable JSON exits 0 in lib/command-parse.js, which is
29
+ // fail-OPEN by design there.
23
30
 
24
31
  // ---------------------------------------------------------------------------
25
32
  // RECURSIVE RE-EVALUATION, not blanket deny (TASK-028). The rule this hook now
@@ -35,6 +35,14 @@ function readHookInput(handler) {
35
35
  * Split a command into independently-inspectable segments. Pipes are included
36
36
  * alongside the separators so a blocked command cannot hide behind
37
37
  * `&&`, `;`, `||`, or `| tail -20`.
38
+ *
39
+ * QUOTING-UNAWARE, and every caller inherits it: the split is a plain regex, so
40
+ * a separator inside quotes still splits (`grep "A|B" .env` becomes `grep "A`
41
+ * and `B" .env`). That direction errs toward more segments and therefore toward
42
+ * blocking, never toward allowing — but a rule that inspects only the FIRST
43
+ * token of a segment can lose its match when a token is torn in half, which is
44
+ * why env-content-read-guard.js re-runs its check over the whole command when
45
+ * it sees both a quote and a pipe.
38
46
  */
39
47
  function splitSegments(cmd) {
40
48
  return String(cmd ?? '').split(/;|&&|\|\||\|/).map(s => s.trim()).filter(Boolean);
@@ -4,6 +4,24 @@
4
4
  * serena-languages.js — reads project/global Serena config for enabled languages
5
5
  * and maps them to file extensions for use in enforcement hooks.
6
6
  *
7
+ * ── This is a library, not a hook ─────────────────────────────────────────
8
+ * It is never wired in lib/scripts/templates/settings-hooks.json, has no
9
+ * stdin/stdout contract, and must never call process.exit or throw. It is loaded
10
+ * at require-time by hooks that are all fail-open, so an exit or an uncaught
11
+ * throw here would take down a tool call the hook was never meant to gate. That
12
+ * is why readFileSafe swallows its catch and why every lookup degrades to "not
13
+ * configured" instead of erroring.
14
+ *
15
+ * Who depends on it:
16
+ * lib/serena.js — getEnabledExtensionsSet, inside isAllowedPath, to decide
17
+ * whether a path's extension belongs to an enabled language. serena.js
18
+ * re-exports the function, so every Serena hook that calls isAllowedPath
19
+ * (edit-guard, write-guard, read-guard, bash-grep-block, …) depends on this
20
+ * file transitively; serena-first-glob-guard.js calls the re-export directly
21
+ * to decide whether a non-code glob is worth enforcing.
22
+ * LANG_EXTS, getEnabledLanguages and buildCodeExtensionsRegex are exported but
23
+ * have no in-repo consumer today — public surface, not dead code.
24
+ *
7
25
  * Resolution order (mirrors Serena itself):
8
26
  * 1. ~/.serena/serena_config.yml — global defaults
9
27
  * 2. {cwd}/.serena/project.yml — project override (wins when languages: present)
@@ -22,9 +40,18 @@ const os = require('os');
22
40
 
23
41
  const GLOBAL_CONFIG = path.join(os.homedir(), '.serena', 'serena_config.yml');
24
42
 
25
- // Serena language name → file extensions (lowercase, no leading dot)
43
+ // Serena language name → file extensions (lowercase, no leading dot).
44
+ // Keys are the exact strings Serena accepts in `languages:`; an unknown key
45
+ // contributes nothing (getEnabledExtensionsSet's `|| []`) rather than throwing,
46
+ // so a typo degrades to narrower scoping, never to a crash.
47
+ // typescript carries js/jsx/mjs/cjs because Serena's TypeScript server also
48
+ // serves plain JavaScript — a JS-only project still writes `typescript`.
26
49
  const LANG_EXTS = {
27
50
  typescript: ['ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs'],
51
+ // The *_jedi / *_ty / *_ccls / *_omnisharp / *_solargraph / *_phpactor keys are
52
+ // not extra languages — they are Serena's alternate language-server backends,
53
+ // and each is a distinct value a user may write in `languages:`. Both spellings
54
+ // must map, or a project on the alternate backend loses language scoping.
28
55
  python: ['py'],
29
56
  python_jedi: ['py'],
30
57
  python_ty: ['py'],
@@ -75,10 +102,16 @@ const LANG_EXTS = {
75
102
  al: ['al'],
76
103
  hlsl: ['hlsl'],
77
104
  msl: ['metal'],
105
+ // FALSE POSITIVE: '.m' is also Objective-C (and Mathematica). A project with
106
+ // matlab enabled will see Objective-C files treated as enabled-language code.
107
+ // Escape hatch: drop matlab from `languages:` in .serena/project.yml.
78
108
  matlab: ['m'],
79
109
  rego: ['rego'],
80
110
  systemverilog: ['sv', 'svh'],
81
111
  haxe: ['hx'],
112
+ // The three CSS-family names deliberately share one extension set, so whichever
113
+ // one a project names in `languages:` covers .css/.scss/.sass — `languages:
114
+ // [css]` on a .scss codebase would otherwise fall out of enforcement entirely.
82
115
  scss: ['scss', 'sass', 'css'],
83
116
  sass: ['scss', 'sass', 'css'],
84
117
  css: ['css', 'scss', 'sass'],
@@ -90,6 +123,26 @@ const LANG_EXTS = {
90
123
  * Returns null when the key is absent.
91
124
  * Returns [] when the key is present but the list is empty.
92
125
  * Returns [...] for a populated list (inline or block form).
126
+ *
127
+ * The null/[] split is load-bearing, not stylistic — getEnabledLanguages uses it
128
+ * to decide whether project.yml overrides the global config. Do not normalise
129
+ * null to [].
130
+ *
131
+ * Hand-rolled instead of js-yaml because the hooks must run with zero
132
+ * dependencies: package.json declares no `dependencies` or `devDependencies` at
133
+ * all, and install-global.sh rsyncs lib/hooks/ into ~/.claude/hooks/, where the
134
+ * scripts execute standalone with no node_modules anywhere on the resolution
135
+ * path. A require('js-yaml') there would throw MODULE_NOT_FOUND on every tool
136
+ * call that triggers a Serena hook. The price is that only the two forms below
137
+ * parse — anchors, flow maps, and multi-line quoted scalars all read as "key
138
+ * absent", which degrades to the caller's static fallback rather than erroring.
139
+ *
140
+ * Accepted forms (block items may sit at any indentation, including column 0):
141
+ * languages: [] → []
142
+ * languages: [typescript, python] → ['typescript', 'python']
143
+ * languages: → ['typescript', 'python']
144
+ * - typescript
145
+ * - python
93
146
  */
94
147
  function parseLanguagesFromYaml(content) {
95
148
  if (!content) return null;
@@ -106,17 +159,33 @@ function parseLanguagesFromYaml(content) {
106
159
  const keyMatch = content.match(/^languages\s*:/m);
107
160
  if (!keyMatch) return null;
108
161
 
162
+ // KNOWN DEFECT, left unfixed (this pass is comments-only): the regex above is
163
+ // ^-anchored, but indexOf is not — it searches from position 0 for the literal
164
+ // matched text ("languages:"). An earlier occurrence of that substring, e.g.
165
+ // inside a comment or as the tail of a key such as `default_languages:`, makes
166
+ // the slice start in the wrong place and the block items are read from the
167
+ // wrong region of the file. Inline form returns before reaching this line, so
168
+ // only block form is affected.
109
169
  const afterKey = content.slice(content.indexOf(keyMatch[0]) + keyMatch[0].length);
110
170
  const items = [];
111
171
  for (const line of afterKey.split('\n')) {
112
172
  if (/^\s*#/.test(line)) continue; // skip comment lines
173
+ // A block item always starts with '-' (at any indentation), so a line
174
+ // beginning with a letter at column 0 is the next top-level key and the list
175
+ // has ended. Without this the loop swallows the rest of the file.
113
176
  if (/^[a-zA-Z]/.test(line)) break; // next top-level key — stop
177
+ // \S+ stops at the first space, so a quoted value containing whitespace
178
+ // parses as its first word. No Serena language name contains a space, so this
179
+ // has no real-world false positive today.
114
180
  const m = line.match(/^\s*-\s*(['"]?)(\S+)\1/);
115
181
  if (m) items.push(m[2]);
116
182
  }
117
183
  return items;
118
184
  }
119
185
 
186
+ // Missing file, unreadable file, and permission denied all mean the same thing
187
+ // here: "not configured". This module is required by fail-open hooks, so it must
188
+ // never throw — see the library note at the top of the file.
120
189
  function readFileSafe(filePath) {
121
190
  try { return fs.readFileSync(filePath, 'utf8'); } catch { return null; }
122
191
  }
@@ -125,11 +194,26 @@ function readFileSafe(filePath) {
125
194
  * Returns the list of enabled language names for the current working directory.
126
195
  * Project config ({cwd}/.serena/project.yml) overrides the global config when
127
196
  * it provides a non-null languages list (even an empty one).
197
+ *
198
+ * "Even an empty one" is the entire reason parseLanguagesFromYaml distinguishes
199
+ * null from []: `languages: []` in project.yml is an authoritative "this project
200
+ * scopes to nothing", and it has to outrank a populated global list. Collapse
201
+ * the two and such a project silently inherits whatever the user happens to have
202
+ * in ~/.serena/serena_config.yml.
203
+ *
204
+ * process.cwd() is the project root only because Claude Code runs hooks from it.
205
+ * This module does no repo-root discovery, so a caller that has chdir'd
206
+ * elsewhere resolves the wrong project.yml and gets the global list instead.
128
207
  */
129
208
  function getEnabledLanguages() {
130
209
  const globalLangs = parseLanguagesFromYaml(readFileSafe(GLOBAL_CONFIG));
131
210
  const projectYml = path.join(process.cwd(), '.serena', 'project.yml');
132
211
  const projectLangs = parseLanguagesFromYaml(readFileSafe(projectYml));
212
+ // The trailing `|| []` deliberately collapses null/[] for callers — downstream
213
+ // only cares about the resulting set. Consequence worth knowing: "no languages
214
+ // configured" reaches serena.js's isAllowedPath as an empty set, and that
215
+ // branch falls back to the static CODE_EXTENSIONS list. An empty result
216
+ // therefore widens enforcement to the built-in defaults; it does not disable it.
133
217
  return (projectLangs !== null ? projectLangs : globalLangs) || [];
134
218
  }
135
219
 
@@ -148,6 +232,15 @@ function getEnabledExtensionsSet() {
148
232
  /**
149
233
  * Returns a RegExp matching file paths whose extension belongs to an enabled
150
234
  * language, or null when no languages are configured.
235
+ *
236
+ * Callers must read null as "no language scoping available" and fall back to
237
+ * their own static list — null is not "matches nothing". No in-repo caller today
238
+ * (see the consumer list at the top); this is public surface, not dead code.
239
+ *
240
+ * Extensions are interpolated unescaped. That is safe only because every value
241
+ * in LANG_EXTS is [a-z0-9]+ — an extension containing a regex metacharacter
242
+ * ('.', '+', '*') would silently corrupt the alternation rather than fail, so
243
+ * keep LANG_EXTS values alphanumeric.
151
244
  */
152
245
  function buildCodeExtensionsRegex() {
153
246
  const exts = getEnabledExtensionsSet();