@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/lib/serena.js
CHANGED
|
@@ -33,6 +33,28 @@
|
|
|
33
33
|
*
|
|
34
34
|
* No network, no MCP runtime introspection, no dependency on Serena being
|
|
35
35
|
* installed — detection (if used) reads user-level Claude Code config.
|
|
36
|
+
*
|
|
37
|
+
* ── This is a library, not a hook ─────────────────────────────────────────
|
|
38
|
+
* It is never wired in lib/scripts/templates/settings-hooks.json, has no
|
|
39
|
+
* stdin/stdout contract, and must never call process.exit — every consumer is
|
|
40
|
+
* fail-open, and an uncaught throw here would take down a tool call the hook
|
|
41
|
+
* was never meant to gate. Hence the swallowed catches throughout: silent
|
|
42
|
+
* degradation is the correct failure mode for this file specifically.
|
|
43
|
+
*
|
|
44
|
+
* Nine hooks require it (all siblings in ../, installed to ~/.claude/hooks/):
|
|
45
|
+
* serena-first-guard.js Grep symbol detection
|
|
46
|
+
* serena-first-glob-guard.js Glob symbol detection ('glob' dialect)
|
|
47
|
+
* serena-bash-grep-block.js Bash symbol detection ('bash') + paths
|
|
48
|
+
* serena-first-read-guard.js Read state file, gates, isAllowedPath
|
|
49
|
+
* serena-edit-guard.js Edit|MultiEdit isAllowedPath + block copy
|
|
50
|
+
* serena-write-guard.js Write isAllowedPath + block copy
|
|
51
|
+
* serena-usage-tracker.js PostToolUse(+Failure) state file, health
|
|
52
|
+
* serena-session-reset.js SessionStart state file path
|
|
53
|
+
* serena-pre-delegation.js Agent fail-open gate only
|
|
54
|
+
* A behaviour change here lands in all nine at once and there is no way to roll
|
|
55
|
+
* one back independently — which is why the call-site differences are expressed
|
|
56
|
+
* as explicit `opts` (see isCodeSymbol's dialect table) rather than as branches
|
|
57
|
+
* on who is calling.
|
|
36
58
|
*/
|
|
37
59
|
|
|
38
60
|
const fs = require('fs');
|
|
@@ -445,6 +467,26 @@ function defaultHealth() {
|
|
|
445
467
|
// each other's updates. This fails open by design — a hook that can't get
|
|
446
468
|
// the lock within budget proceeds unlocked rather than hanging; hooks must
|
|
447
469
|
// never block indefinitely.
|
|
470
|
+
// Why these three numbers. The critical section is a read, a JSON.parse, an
|
|
471
|
+
// in-memory mutate and an atomic rename — sub-millisecond in practice. A lock
|
|
472
|
+
// still held after LOCK_STALE_MS (750ms) is therefore not contended, it is
|
|
473
|
+
// orphaned by a hook process that died mid-cycle; nothing auto-releases a plain
|
|
474
|
+
// marker file, so without a staleness rule one crash wedges every later state
|
|
475
|
+
// write for the rest of the session. 750ms sits far enough above the real cost
|
|
476
|
+
// that clearing a genuinely live holder takes a pathological stall.
|
|
477
|
+
//
|
|
478
|
+
// LOCK_RETRY_BUDGET_MS (250ms) is the other side of the trade: it caps what a
|
|
479
|
+
// *waiting* hook adds to a tool call it was never meant to slow down. On
|
|
480
|
+
// exhaustion the caller proceeds unlocked and best-effort — a lost counter
|
|
481
|
+
// update is cheap, a PreToolUse hook that hangs is not. Being well under
|
|
482
|
+
// LOCK_STALE_MS means a waiter normally gives up rather than clearing a lock
|
|
483
|
+
// whose holder is merely slow. (Staleness is judged from the lock file's own
|
|
484
|
+
// mtime, not from how long this waiter has waited, so a waiter that arrives late
|
|
485
|
+
// in a stale lock's life still clears it immediately — that is the self-heal
|
|
486
|
+
// working, not a violation of the budget.)
|
|
487
|
+
//
|
|
488
|
+
// The backoff ladder tops out at 80ms, so the budget covers about five wakeups:
|
|
489
|
+
// enough to yield to a real holder, few enough that waiting is never the cost.
|
|
448
490
|
const LOCK_STALE_MS = 750;
|
|
449
491
|
const LOCK_RETRY_BUDGET_MS = 250;
|
|
450
492
|
const LOCK_BACKOFF_MS = [10, 20, 40, 80];
|
|
@@ -580,10 +622,30 @@ function classifySerenaFailure(errorPayload) {
|
|
|
580
622
|
// Tool-level: the server answered, the query just didn't resolve, or it
|
|
581
623
|
// declined for a benign/config reason (e.g. the file's language isn't
|
|
582
624
|
// enabled in .serena/project.yml — a normal, expected response).
|
|
625
|
+
// The alternation is grouped by what Serena's error strings actually say, not
|
|
626
|
+
// by an error taxonomy: query misses ("not found", "no results", "no matching",
|
|
627
|
+
// "no symbol", "could not find"), path misses ("does not exist", "no such
|
|
628
|
+
// file/symbol/path/directory"), the "error at <location>" form emitted for a
|
|
629
|
+
// bad location, and — the group that matters most — the language-config
|
|
630
|
+
// declines ("cannot extract symbols", "active languages", "unsupported
|
|
631
|
+
// language", "no language server"). A file whose language is not enabled in
|
|
632
|
+
// .serena/project.yml fails on EVERY call, so misfiling that group as
|
|
633
|
+
// transport would shell out to pgrep on each one and, the first time the probe
|
|
634
|
+
// came back empty, disable Serena-first enforcement for the whole project on
|
|
635
|
+
// the strength of a perfectly healthy server declining a file type.
|
|
583
636
|
if (/not found|no results|no matching|no symbol|could not find|error searching|error finding|does not exist|no such (?:file|symbol|path|directory)|error at |cannot extract symbols|active languages|unsupported language|no language server/i.test(s)) {
|
|
584
637
|
return 'tool';
|
|
585
638
|
}
|
|
586
639
|
// Transport-level: the server is unreachable / the pipe broke.
|
|
640
|
+
// Transport-level: nothing in this alternation describes a query, only a pipe.
|
|
641
|
+
// `closed`, `reset` and `connection` are bare because they arrive with no
|
|
642
|
+
// stable prefix ("connection closed", "transport closed", "socket reset").
|
|
643
|
+
//
|
|
644
|
+
// Ordering is load-bearing: a single error string can match both lists
|
|
645
|
+
// ("connection to the language server closed: symbol not found"), and first
|
|
646
|
+
// match wins, so the narrower tool-level test must run first. Swapping the two
|
|
647
|
+
// blocks would route ordinary query misses that merely mention a connection
|
|
648
|
+
// into the health-assessment path.
|
|
587
649
|
if (/timeout|timed out|connection|refused|econnrefused|socket|epipe|closed|disconnect|not connected|unreachable|reset|broken pipe|hang/i.test(s)) {
|
|
588
650
|
return 'transport';
|
|
589
651
|
}
|
|
@@ -630,8 +692,43 @@ function isSerenaProcessAlive(projectDir) {
|
|
|
630
692
|
// slightly different allowlists — those genuine differences are expressed via
|
|
631
693
|
// `opts`, so identical inputs yield identical block/allow decisions.
|
|
632
694
|
|
|
695
|
+
// Zero-width and bidi formatting characters. They render as nothing, so
|
|
696
|
+
// `create<ZWSP>Order` is visually identical to `createOrder` while every ASCII
|
|
697
|
+
// shape regex below fails to match it — a single pasted character is enough to
|
|
698
|
+
// walk a symbol search past the guards. Stripping is opt-in (`stripZeroWidth`)
|
|
699
|
+
// because the three call sites handle it differently: the Glob guard sets the
|
|
700
|
+
// flag, the Bash guard strips them in its own `clean` callback before tokens
|
|
701
|
+
// ever reach here, and the Grep guard (serena-first-guard.js) does NEITHER.
|
|
702
|
+
//
|
|
703
|
+
// SUSPECTED DEFECT — annotated, deliberately not fixed in this comments-only
|
|
704
|
+
// pass. That third case leaves the exact bypass this constant exists to close
|
|
705
|
+
// still open on the Grep surface: a zero-width character inside a Grep pattern
|
|
706
|
+
// token is neither stripped nor rejected (it is not a regex metacharacter, so
|
|
707
|
+
// rejectRegexSpecials does not catch it). The fix is one option at that call
|
|
708
|
+
// site, but it needs its own regression test rather than riding along here.
|
|
633
709
|
const SYMBOL_ZERO_WIDTH = /[--]/g;
|
|
634
710
|
|
|
711
|
+
// Why this list is ~150 entries long, and what earns a place on it. The Glob
|
|
712
|
+
// guard hands over a pattern already shredded into fragments — `src/**/*Modal.tsx`
|
|
713
|
+
// becomes `src`, `Modal`, `tsx` — and by the time a fragment reaches
|
|
714
|
+
// isCodeSymbol there is no context left to distinguish "this was the extension"
|
|
715
|
+
// from "this was a symbol". So every fragment a legitimate file-discovery glob
|
|
716
|
+
// routinely produces has to be named here, or the guard blocks ordinary work:
|
|
717
|
+
// extensions, directory names, file stems, framework/tool config stems, and the
|
|
718
|
+
// directive words people search for. The length is the cost of exact matching;
|
|
719
|
+
// each entry is one word that would otherwise be judged on its shape alone.
|
|
720
|
+
//
|
|
721
|
+
// The bar for adding an entry: the token shows up in globs people write to find
|
|
722
|
+
// files by location or kind, and nobody writes it meaning a symbol. `Modal`
|
|
723
|
+
// fails that test (it is a real component name) and is deliberately absent;
|
|
724
|
+
// `middleware`, `providers`, and `transformers` pass it and are present even
|
|
725
|
+
// though each is also a plausible identifier — because here a false block costs
|
|
726
|
+
// a real search while a false allow costs only a slower route to the same files.
|
|
727
|
+
//
|
|
728
|
+
// Matched lowercased and EXACTLY. Substring matching would exempt `UserService`
|
|
729
|
+
// for containing `service`, which is the entire class of token this guard exists
|
|
730
|
+
// to catch. (`next` and `turbo` appear under two group headings; Set membership
|
|
731
|
+
// makes the duplicate inert.)
|
|
635
732
|
// Glob guard's exact-match skip set: extensions, common dirs/stems, framework
|
|
636
733
|
// config names, directives. Checked case-insensitively.
|
|
637
734
|
const GLOB_SKIP_EXACT = new Set([
|
|
@@ -665,6 +762,37 @@ const GLOB_SKIP_EXACT = new Set([
|
|
|
665
762
|
'require', 'http', 'https',
|
|
666
763
|
]);
|
|
667
764
|
|
|
765
|
+
// ── The kebab carve-out (Grep dialect only) ────────────────────────────────
|
|
766
|
+
// A kebab token is normally a filename, not a symbol, and the Glob dialect
|
|
767
|
+
// rejects the shape outright for exactly that reason. The Grep dialect cannot
|
|
768
|
+
// afford to: in a React/Next codebase the component and its file share a name,
|
|
769
|
+
// so a developer greps `user-modal` meaning the component. These three regexes
|
|
770
|
+
// triage that, and they are tested in the order they are declared.
|
|
771
|
+
//
|
|
772
|
+
// KEBAB_TAILWIND_PREFIX — the dominant false positive by volume, and the reason
|
|
773
|
+
// the carve-out needs a reject list at all. A Tailwind project's markup is
|
|
774
|
+
// wall-to-wall `text-sm`, `bg-white`, `hover:bg-gray-100`, `max-w-md`,
|
|
775
|
+
// `data-state` — every one a kebab token of symbol-ish length. Grepping a
|
|
776
|
+
// utility class is a styling search over markup, never a symbol lookup, and
|
|
777
|
+
// Serena has nothing better to offer for it, so these must fall through to Grep
|
|
778
|
+
// or the guard makes CSS work impossible. The list is the Tailwind utility
|
|
779
|
+
// prefix set (spacing, sizing, colour, layout, typography, transition, and the
|
|
780
|
+
// `hover:`/`focus:`/`active:`/`group-` state variants); it is not exhaustive,
|
|
781
|
+
// it stops where class attributes stop.
|
|
782
|
+
//
|
|
783
|
+
// KEBAB_COMPONENT_SUFFIX — the inverse judgement. A kebab token ending in a
|
|
784
|
+
// UI-part noun (`user-modal`, `date-picker`, `nav-bar`, `error-boundary`) names
|
|
785
|
+
// something that exists as a symbol, so Serena can answer for it. The trailing
|
|
786
|
+
// `s?` covers the plural filename convention (`user-cards`). The agent-role tail
|
|
787
|
+
// (`-runner`, `-reviewer`, `-checker`, `-resolver`, `-guard`, `-enforcer`) is
|
|
788
|
+
// not decoration: this repo and the kit it was ported from name their own
|
|
789
|
+
// subagents and hook scripts that way, so it is the local vocabulary and the
|
|
790
|
+
// tokens actually get searched for.
|
|
791
|
+
//
|
|
792
|
+
// KEBAB_DOMAIN_PREFIX — the same call from the other end. A token whose FIRST
|
|
793
|
+
// segment is a code-layer word (`actions-`, `helpers-`, `utils-`, `hooks-`,
|
|
794
|
+
// `types-`, `constants-`, `validations-`, `services-`) is naming code whatever
|
|
795
|
+
// follows it, so the suffix never has to be enumerated.
|
|
668
796
|
// Guard's tailwind-utility prefixes — kebab tokens starting with these are
|
|
669
797
|
// styling classes, never symbols.
|
|
670
798
|
const KEBAB_TAILWIND_PREFIX = /^(text-|bg-|border-|font-|hover:|focus:|active:|group-|ring-|shadow-|rounded-|flex-|grid-|gap-|space-|divide-|overflow-|whitespace-|break-|leading-|tracking-|align-|justify-|items-|self-|order-|col-|row-|transition-|duration-|ease-|animate-|scale-|rotate-|translate-|origin-|cursor-|select-|resize-|appearance-|outline-|decoration-|underline-|line-|placeholder-|caret-|accent-|sr-|z-|opacity-|w-|h-|p-|m-|px-|py-|pt-|pb-|pl-|pr-|mx-|my-|mt-|mb-|ml-|mr-|max-|min-|inset-|top-|right-|bottom-|left-|float-|data-)/;
|
|
@@ -685,12 +813,63 @@ const KEBAB_DOMAIN_PREFIX = /^(actions?|helpers?|utils?|hooks?|types?|constants?
|
|
|
685
813
|
function isCodeSymbol(raw, opts = {}) {
|
|
686
814
|
if (raw == null) return false;
|
|
687
815
|
let s = String(raw);
|
|
816
|
+
// Ordering: strip zero-width first, then measure. Measuring first would let a
|
|
817
|
+
// padded 3-character name clear the floor and then fail every shape test below
|
|
818
|
+
// — allowed, but for the wrong reason, and silently.
|
|
819
|
+
//
|
|
820
|
+
// The 4-character floor and the whitespace reject are the two rules every
|
|
821
|
+
// dialect shares. Below 4 characters the shape tests stop discriminating (`ab`,
|
|
822
|
+
// `x1`, `Foo` are as likely to be prose as code) and find_symbol is not the
|
|
823
|
+
// better tool for such a name anyway. Whitespace means the token is a phrase,
|
|
824
|
+
// and a phrase is a text search — which is precisely what Grep is for.
|
|
688
825
|
if (opts.stripZeroWidth) s = s.replace(SYMBOL_ZERO_WIDTH, '');
|
|
689
826
|
if (s.length < 4) return false;
|
|
690
827
|
if (/\s/.test(s)) return false;
|
|
691
828
|
|
|
829
|
+
// Grep dialect only. Its tokens arrive raw, so one still carrying `(`, `[`,
|
|
830
|
+
// `\`, `^`, `$`, `*`, `+`, `?` or `&` is a regex fragment, not a name — and
|
|
831
|
+
// Serena's find_symbol takes a name, not a pattern. Blocking there would trade
|
|
832
|
+
// a working regex search for a tool that cannot express it. The other two
|
|
833
|
+
// dialects never need this: the Bash call site strips the same metacharacters
|
|
834
|
+
// in `clean`, and the Glob splitRe consumes them as delimiters.
|
|
692
835
|
if (opts.rejectRegexSpecials && /[&?+[\]{}()\\^$*]/.test(s)) return false;
|
|
693
836
|
|
|
837
|
+
// ── The three allowlist dialects ─────────────────────────────────────────
|
|
838
|
+
// This is the entire false-positive surface of three hooks, so the differences
|
|
839
|
+
// below are deliberate rather than drift. Every dialect answers one question —
|
|
840
|
+
// "would blocking this token cost the caller a search Serena cannot do?" — for
|
|
841
|
+
// a different input shape:
|
|
842
|
+
//
|
|
843
|
+
// 'guard' serena-first-guard.js (Grep). Tokens are raw pattern fragments,
|
|
844
|
+
// split on `|` and nothing else, so they can still be comment
|
|
845
|
+
// markers, quoted strings, JS keywords, or call syntax. Hence the
|
|
846
|
+
// widest reject list (`^//`, `^#`, `^.`, `^['"` + backtick`]`,
|
|
847
|
+
// `require(`, `console.`, `use client|server`): every one of those
|
|
848
|
+
// is a thing people grep for, and none of them is a symbol name.
|
|
849
|
+
// 'bash' serena-bash-grep-block.js (a grep/rg command line). The call site
|
|
850
|
+
// has already stripped regex metacharacters in its `clean`
|
|
851
|
+
// callback, so the list is shorter — but it adds
|
|
852
|
+
// `^[a-z]+-[a-z]+`, rejecting kebab outright. A shell grep for
|
|
853
|
+
// `user-modal` is usually hunting a filename or a CSS class, and
|
|
854
|
+
// this dialect never sets kebabComponents, so the two agree.
|
|
855
|
+
// 'glob' serena-first-glob-guard.js (a file glob). Tokens are path
|
|
856
|
+
// fragments, so prefix rules do not apply; it uses GLOB_SKIP_EXACT
|
|
857
|
+
// — an exact-match vocabulary of everything a legitimate glob
|
|
858
|
+
// produces — plus a full kebab-filename reject, because inside a
|
|
859
|
+
// glob a kebab token IS a filename.
|
|
860
|
+
//
|
|
861
|
+
// Passing no allowlist (the default) applies none of this: only the shared
|
|
862
|
+
// floors above and the shape tests below. Nothing in this repo calls it that
|
|
863
|
+
// way. It is the honest default for a new call site that has not yet decided
|
|
864
|
+
// what its tokens look like, and it is also the STRICTEST — with no rejects it
|
|
865
|
+
// calls more things symbols and therefore blocks more.
|
|
866
|
+
//
|
|
867
|
+
// Two rules recur in all three lists and carry most of the weight:
|
|
868
|
+
// `^[A-Z_]{3,}$` (SCREAMING_SNAKE is a constant or an env var — grep is the
|
|
869
|
+
// right tool, find_symbol is not) and `^[a-z]{1,8}$` (a short all-lowercase
|
|
870
|
+
// word is too generic to be worth a symbol lookup). `^\d` and `^http` appear
|
|
871
|
+
// in the two prefix-based dialects; the glob dialect covers the same ground by
|
|
872
|
+
// exact match (`http`, `https` are in GLOB_SKIP_EXACT).
|
|
694
873
|
if (opts.allowlist === 'guard') {
|
|
695
874
|
const allow = [
|
|
696
875
|
/^(TODO|FIXME|HACK|XXX|NOTE)/i,
|
|
@@ -710,6 +889,12 @@ function isCodeSymbol(raw, opts = {}) {
|
|
|
710
889
|
];
|
|
711
890
|
if (skip.some(rx => rx.test(s))) return false;
|
|
712
891
|
} else if (opts.allowlist === 'glob') {
|
|
892
|
+
// Ordering trap: the kebab-filename reject below sits ABOVE the
|
|
893
|
+
// kebabComponents carve-out further down, so a caller passing both
|
|
894
|
+
// `allowlist: 'glob'` and `kebabComponents: true` would never reach the
|
|
895
|
+
// carve-out and every kebab component name would be allowed. No call site
|
|
896
|
+
// does that today — the two options are mutually exclusive by intent, and
|
|
897
|
+
// nothing here enforces it.
|
|
713
898
|
if (GLOB_SKIP_EXACT.has(s.toLowerCase())) return false;
|
|
714
899
|
if (/^[a-z]{1,8}$/.test(s)) return false;
|
|
715
900
|
if (/^[A-Z_]{3,}$/.test(s)) return false;
|
|
@@ -717,6 +902,18 @@ function isCodeSymbol(raw, opts = {}) {
|
|
|
717
902
|
}
|
|
718
903
|
|
|
719
904
|
// Guard's kebab carve-out: some kebab tokens ARE symbols.
|
|
905
|
+
// Reached only from the Grep dialect — it is the sole call site that sets
|
|
906
|
+
// kebabComponents. The `^[a-z]+-[a-z]/` test scopes the block to lowercase
|
|
907
|
+
// kebab; anything else falls straight through to the shape tests below.
|
|
908
|
+
//
|
|
909
|
+
// Overlaps resolve top-down, and there are real ones: `grid-item` and
|
|
910
|
+
// `text-field` carry a Tailwind prefix *and* a component suffix, and the
|
|
911
|
+
// prefix wins, so they are treated as styling and the Grep is allowed. That
|
|
912
|
+
// error direction is the cheap one — a permitted Grep costs a slower route to
|
|
913
|
+
// the same lines, while a wrong block costs a search Serena cannot perform.
|
|
914
|
+
//
|
|
915
|
+
// The trailing `return false` is the actual policy of this block: an
|
|
916
|
+
// unrecognised kebab token is a filename until proven otherwise.
|
|
720
917
|
if (opts.kebabComponents && /^[a-z]+-[a-z]/.test(s)) {
|
|
721
918
|
if (KEBAB_TAILWIND_PREFIX.test(s)) return false;
|
|
722
919
|
if (KEBAB_COMPONENT_SUFFIX.test(s)) return true;
|
|
@@ -724,6 +921,22 @@ function isCodeSymbol(raw, opts = {}) {
|
|
|
724
921
|
return false;
|
|
725
922
|
}
|
|
726
923
|
|
|
924
|
+
// The shapes that mean "this is an identifier". What each one is really doing:
|
|
925
|
+
// camelCase requires an interior capital; the `{3,}` bound only restates
|
|
926
|
+
// the shared 4-character floor above.
|
|
927
|
+
// PascalCase requires the *second* character to be a letter, so `S3Client`
|
|
928
|
+
// and `X11Server` are not recognised. That miss is real; no
|
|
929
|
+
// rationale for excluding a digit there is recoverable from the
|
|
930
|
+
// code or the README — verify before relying on it either way.
|
|
931
|
+
// snake_case demands three or more segments AND 9+ characters, because
|
|
932
|
+
// two-segment snake (`user_id`, `my_var`, `is_open`) is far more
|
|
933
|
+
// often a column, a flag, or a variable than a function anyone
|
|
934
|
+
// would navigate to — and blocking those would break routine
|
|
935
|
+
// grepping of SQL and config text.
|
|
936
|
+
// dotted Grep-only (`mcp.Tool`, `router.push`): a module-qualified name.
|
|
937
|
+
// The Bash dialect splits on `.` and the Glob dialect treats it
|
|
938
|
+
// as a path separator, so the raw-token dialect is the only one
|
|
939
|
+
// that can ever see one intact.
|
|
727
940
|
const isCamelCase = /^[a-z][a-zA-Z0-9]{3,}$/.test(s) && /[A-Z]/.test(s);
|
|
728
941
|
const isPascalCase = /^[A-Z][a-zA-Z][a-zA-Z0-9]{2,}$/.test(s);
|
|
729
942
|
const isSnakeCaseFn = /^[a-z]+(_[a-z]+){2,}$/.test(s) && s.length >= 9;
|
|
@@ -738,6 +951,21 @@ function isCodeSymbol(raw, opts = {}) {
|
|
|
738
951
|
* optionally cleans each token before trimming. Remaining opts are forwarded
|
|
739
952
|
* to isCodeSymbol.
|
|
740
953
|
*/
|
|
954
|
+
// The tokenizer belongs to the call site, not to this function, because the
|
|
955
|
+
// three pattern syntaxes disagree about what a delimiter is:
|
|
956
|
+
// Grep splitRe '|' regex alternation and nothing else; a dot
|
|
957
|
+
// stays inside the token (see dottedSymbol).
|
|
958
|
+
// Bash splitRe /\\?\||\./ alternation plus dots — a shell grep pattern
|
|
959
|
+
// keeps `mcp.Tool` as one token, and the
|
|
960
|
+
// call site's `clean` strips the dot, which
|
|
961
|
+
// would manufacture `mcpTool`, a camelCase
|
|
962
|
+
// false positive out of thin air.
|
|
963
|
+
// Glob splitRe /[*/.\\{}...]+/ all punctuation — a glob is a path, and its
|
|
964
|
+
// punctuation is structure, not content.
|
|
965
|
+
// Choosing wrong does not fail loudly: it silently changes which tokens exist,
|
|
966
|
+
// and therefore which searches get blocked. `opts` is forwarded whole to
|
|
967
|
+
// isCodeSymbol, so a call site's splitRe and its dialect must be picked together
|
|
968
|
+
// — see the dialect table in isCodeSymbol.
|
|
741
969
|
function extractSymbolsFromPattern(pattern, opts = {}) {
|
|
742
970
|
const p = String(pattern ?? '');
|
|
743
971
|
const splitRe = opts.splitRe || '|';
|
|
@@ -1,9 +1,35 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
'use strict';
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
4
|
+
/**
|
|
5
|
+
* mv-absolute-path-block.js — PreToolUse / Bash (wiring adds `if: Bash(mv *)`)
|
|
6
|
+
*
|
|
7
|
+
* Blocks: an `mv` with an absolute-path argument rooted outside the hook's idea
|
|
8
|
+
* of the project root (see BUG-0005 below — that idea is not the session's) —
|
|
9
|
+
* the "I thought I was somewhere else" move that lands a file in /etc, /usr,
|
|
10
|
+
* or a neighbouring repo.
|
|
11
|
+
* Why a hook: whether an absolute path is acceptable depends on where the
|
|
12
|
+
* project root is, and a settings.json pattern cannot see the project root.
|
|
13
|
+
* Denying every absolute-path mv would deny the legitimate in-project ones
|
|
14
|
+
* too, and enumerating the roots worth protecting is precisely the unbounded
|
|
15
|
+
* list a hook exists to replace. The verdict also has to arrive as a
|
|
16
|
+
* CORRECTION ("check that you are in the project root") rather than a
|
|
17
|
+
* prohibition, and a deny rule cannot carry a message at all.
|
|
18
|
+
* Fails: open — unparseable stdin exits 0 silently at the JSON.parse catch
|
|
19
|
+
* below. A payload that parses to a non-object (`null`) throws on
|
|
20
|
+
* `data.tool_name` and exits non-zero, which Claude Code reads as a
|
|
21
|
+
* NON-blocking hook error: stderr is surfaced and the tool call proceeds
|
|
22
|
+
* anyway. Both paths allow. This file does not use lib/command-parse.js's
|
|
23
|
+
* readHookInput, so there is no handler-level catch; of the hooks in this
|
|
24
|
+
* directory only interpreter-indirection-guard.js genuinely fails closed.
|
|
25
|
+
* False positives: a pipeline is not a segment boundary here, so a later
|
|
26
|
+
* stage's absolute path is attributed to the `mv` —
|
|
27
|
+
* `mv notes.md archive.md | tee /var/log/mvlog.txt` denies a move that is
|
|
28
|
+
* entirely in-project (BUG-0006, annotated at the segment split below) —
|
|
29
|
+
* escape hatch: join with `&&` instead of `|`, which IS a segment boundary,
|
|
30
|
+
* so the `mv` is then judged on its own two operands.
|
|
31
|
+
* See README.md § Safety / policy hooks for the full rationale.
|
|
32
|
+
*/
|
|
7
33
|
|
|
8
34
|
const path = require('path');
|
|
9
35
|
|
|
@@ -18,10 +44,56 @@ process.stdin.on('end', () => {
|
|
|
18
44
|
const fullCmd = String(data.tool_input?.command ?? '').trim();
|
|
19
45
|
if (!fullCmd) process.exit(0);
|
|
20
46
|
|
|
47
|
+
// BUG-0005 — UNEXPLAINED DIVERGENCE, annotated here and deliberately not fixed.
|
|
48
|
+
// Every sibling guard that needs a project root reads `data.cwd` off the hook
|
|
49
|
+
// payload and falls back to `process.cwd()` only if it is missing
|
|
50
|
+
// (protected-write-guard.js:189, claude-settings-guard.js:192,
|
|
51
|
+
// interpreter-indirection-guard.js:579, serena-pre-delegation.js:95). This one
|
|
52
|
+
// alone asks node and never looks at the payload. `data.cwd` is the
|
|
53
|
+
// authoritative session cwd Claude Code reports for the tool call;
|
|
54
|
+
// `process.cwd()` is merely wherever the node process running this hook was
|
|
55
|
+
// started. When the two differ the check inverts in BOTH directions: absolute
|
|
56
|
+
// paths that really are in-project stop matching `cwdWithSep` and get denied,
|
|
57
|
+
// while paths under node's cwd but outside the session's project get allowed.
|
|
58
|
+
// No comment, commit message, or test explains the choice, which is why it is
|
|
59
|
+
// filed rather than assumed intentional. Do not swap it in passing — it is a
|
|
60
|
+
// behaviour change to a live shipped control and belongs to BUG-0005.
|
|
21
61
|
const cwd = process.cwd();
|
|
22
62
|
const cwdWithSep = cwd + path.sep;
|
|
23
63
|
|
|
24
64
|
// Split on command separators and inspect each segment independently.
|
|
65
|
+
//
|
|
66
|
+
// BUG-0006 — DIVERGENCE, annotated and deliberately not fixed: this list is
|
|
67
|
+
// `;`, `&&`, `||` but NOT `|`, whereas lib/command-parse.js's splitSegments
|
|
68
|
+
// (:48) includes the pipe. Read the next three paragraphs before touching it,
|
|
69
|
+
// because the obvious reading of this gap is wrong.
|
|
70
|
+
//
|
|
71
|
+
// It is NOT a bypass. `args` is `tokens.slice(mvIdx + 1)` and runs to the end
|
|
72
|
+
// of the segment, straight through any `|`, so an absolute path still lands in
|
|
73
|
+
// `args` regardless of which pipeline stage wrote it:
|
|
74
|
+
// echo x | mv /etc/foo /tmp/bar still denies
|
|
75
|
+
// cat mv | mv /etc/x /tmp/y still denies
|
|
76
|
+
//
|
|
77
|
+
// The actual defect is the inverse — FALSE denials. Operands belonging to a
|
|
78
|
+
// later stage are attributed to the `mv`, so a wholly in-project move that
|
|
79
|
+
// merely logs somewhere absolute is refused:
|
|
80
|
+
// mv notes.md archive.md | tee /var/log/mvlog.txt denies, wrongly
|
|
81
|
+
//
|
|
82
|
+
// WARNING TO THE NEXT READER: the tempting fix — anchor the verb at the head
|
|
83
|
+
// of each segment, the way absolute-path-guard.js does — would OPEN the bypass
|
|
84
|
+
// this only looks like it has. With `|` still absent from the split,
|
|
85
|
+
// `echo x | mv /etc/foo /tmp/bar` is one segment headed by `echo`, and an
|
|
86
|
+
// anchored check would stop seeing the `mv` entirely. Adding `|` to the split
|
|
87
|
+
// and anchoring the verb are a single change, not two; either one alone makes
|
|
88
|
+
// this hook strictly worse. That coupling is why it is filed as BUG-0006
|
|
89
|
+
// instead of patched in place.
|
|
90
|
+
//
|
|
91
|
+
// One nuance if you go to reproduce any of the above: the shipped wiring gates
|
|
92
|
+
// this hook behind `if: Bash(mv *)` (settings-hooks.json:104), so only commands
|
|
93
|
+
// whose first token is `mv` reach the file at all. `echo x | mv /etc/foo …` is
|
|
94
|
+
// filtered out upstream and never arrives, while the false-denial case does,
|
|
95
|
+
// because it starts with `mv`. The gate lives in settings-hooks.json, not
|
|
96
|
+
// here, so the logic above still has to stand on its own if it is relaxed.
|
|
25
97
|
const segments = fullCmd.split(/;|&&|\|\|/).map(s => s.trim()).filter(Boolean);
|
|
26
98
|
|
|
27
99
|
for (const segment of segments) {
|
|
@@ -30,6 +102,15 @@ process.stdin.on('end', () => {
|
|
|
30
102
|
if (mvIdx === -1) continue;
|
|
31
103
|
|
|
32
104
|
// Arguments after 'mv', skipping flags (-n, -f, -v, etc.)
|
|
105
|
+
//
|
|
106
|
+
// `!t.startsWith('-')` is a heuristic, not getopt, and it is safe in this
|
|
107
|
+
// one direction: every mv flag that takes a value takes a PATH as that value
|
|
108
|
+
// (`-t /etc/cron.d`, `--target-directory=/etc/cron.d`). Dropping the flag
|
|
109
|
+
// therefore leaves its value behind in `args`, still inspected — the naive
|
|
110
|
+
// failure mode where a flag swallows the very path you wanted to check
|
|
111
|
+
// cannot occur here. The cost is the mirror case: a file whose name starts
|
|
112
|
+
// with `-` is skipped. That is free, because such a name cannot also start
|
|
113
|
+
// with `/`, and an absolute path is the only thing this hook blocks.
|
|
33
114
|
const args = tokens.slice(mvIdx + 1).filter(t => !t.startsWith('-'));
|
|
34
115
|
|
|
35
116
|
const offendingArg = args.find(arg => {
|
|
@@ -36,6 +36,11 @@
|
|
|
36
36
|
// `npm install -g @playwright/mcp@latest` at the prompt IS gated. Both are
|
|
37
37
|
// correct: consent was given once for the setup script as a whole; an ad-hoc
|
|
38
38
|
// install carries no such consent.
|
|
39
|
+
//
|
|
40
|
+
// Fails: open — matching is pure token inspection with no external input, and a
|
|
41
|
+
// throw exits 0 via lib/command-parse.js. The asymmetry that matters here is
|
|
42
|
+
// coverage rather than failure: a manager or invocation form absent from the
|
|
43
|
+
// tables below is allowed, which is also why the scope note above holds.
|
|
39
44
|
|
|
40
45
|
const { readHookInput, splitSegments, tokenize, deny } = require('./lib/command-parse');
|
|
41
46
|
|
|
@@ -92,6 +97,12 @@ function stripInvocationPrefix(tokens) {
|
|
|
92
97
|
// `uvx --from X` fetches and runs X, so it is an install in everything but
|
|
93
98
|
// name. The flag is located anywhere in the segment rather than at a fixed
|
|
94
99
|
// position, because `uvx --python 3.12 --from X` is equally valid.
|
|
100
|
+
//
|
|
101
|
+
// NOTE: bare `uvx <pkg>` (no `--from`) returns null here and is therefore
|
|
102
|
+
// ALLOWED, even though it fetches and runs a package by the same reasoning
|
|
103
|
+
// above. Whether that is a deliberate scope choice or an oversight is not
|
|
104
|
+
// recoverable from this file or from lib/hooks/README.md — verify before
|
|
105
|
+
// changing, and do not treat the current behaviour as intentional coverage.
|
|
95
106
|
function uvxSource(tokens) {
|
|
96
107
|
for (let i = 1; i < tokens.length; i++) {
|
|
97
108
|
if (tokens[i] === '--from') return tokens[i + 1] ?? '';
|
|
@@ -64,6 +64,13 @@
|
|
|
64
64
|
// unremarkable but which points into ~/.claude/ is not caught.
|
|
65
65
|
// - `git --config-env=alias.x=VAR` reads the value from an environment
|
|
66
66
|
// variable, so the dangerous string never appears in the command. Not covered.
|
|
67
|
+
//
|
|
68
|
+
// Fails: open — all three rules are pure string/path matching over the command
|
|
69
|
+
// itself, with no file read, no subprocess, and no external list, so there is no
|
|
70
|
+
// "could not check" state to fail into. If this hook throws anyway,
|
|
71
|
+
// lib/command-parse.js catches it and exits 0 and the command is allowed.
|
|
72
|
+
// Ambiguous MATCHES go the other way and block — see the inherited false
|
|
73
|
+
// positive above.
|
|
67
74
|
|
|
68
75
|
const path = require('path');
|
|
69
76
|
const os = require('os');
|