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