@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.
- package/lib/hooks/README.md +94 -3
- package/lib/hooks/absolute-path-guard.js +5 -0
- package/lib/hooks/claude-settings-guard.js +5 -0
- package/lib/hooks/env-content-read-guard.js +13 -3
- package/lib/hooks/env-file-guard.js +42 -0
- package/lib/hooks/interpreter-indirection-guard.js +7 -0
- package/lib/hooks/lib/command-parse.js +8 -0
- package/lib/hooks/lib/serena-languages.js +94 -1
- package/lib/hooks/lib/serena.js +228 -0
- package/lib/hooks/mv-absolute-path-block.js +84 -3
- package/lib/hooks/package-install-consent.js +11 -0
- package/lib/hooks/protected-write-guard.js +7 -0
- package/lib/hooks/serena-bash-grep-block.js +507 -44
- package/lib/hooks/serena-first-glob-guard.js +65 -20
- package/lib/hooks/serena-first-guard.js +98 -2
- package/lib/hooks/serena-first-read-guard.js +92 -2
- package/lib/hooks/serena-pre-delegation.js +123 -0
- package/lib/hooks/serena-write-guard.js +56 -3
- package/lib/scripts/README.md +306 -1
- package/lib/scripts/bootstrap-prefs.js +734 -0
- package/lib/scripts/install-global.sh +188 -18
- package/lib/scripts/install-mcps.sh +102 -14
- package/lib/scripts/lib.sh +581 -11
- package/lib/scripts/merge-gitignore.sh +201 -15
- package/lib/scripts/sync-wiki-scaffold.sh +33 -4
- package/lib/scripts/templates/CLAUDE-wiki.md +1 -1
- package/lib/scripts/templates/bootstrap-prefs-schema.json +175 -0
- package/lib/scripts/update-project.sh +42 -9
- package/lib/skills/README.md +2 -1
- package/lib/skills/bootstrap-config/SKILL.md +154 -0
- package/lib/skills/git-commit/SKILL.md +89 -6
- package/lib/skills/research/SKILL.md +34 -3
- package/lib/skills/simplify/SKILL.md +1 -1
- package/lib/skills/uat-auto/SKILL.md +9 -4
- package/lib/skills/uat-auto-plus/SKILL.md +6 -6
- package/lib/skills/uat-generate/SKILL.md +47 -7
- package/lib/skills/uat-walk/UAT-CORE.md +41 -6
- package/lib/skills/wiki-query/SKILL.md +48 -8
- package/package.json +1 -1
package/lib/hooks/README.md
CHANGED
|
@@ -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
|
-
(`:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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();
|