Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

fix: integrate recent hook and docs PRs (#1905)

Affaan Mustafa375d750b4c14
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 71047464f..08db16af5 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -11,7 +11,7 @@
{
"name": "ecc",
"source": "./",
- "description": "The most comprehensive Claude Code plugin — 60 agents, 228 skills, 75 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
+ "description": "The most comprehensive Claude Code plugin — 60 agents, 229 skills, 75 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",
"version": "2.0.0-rc.1",
"author": {
"name": "Affaan Mustafa",
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index e98e81abd..ca38f6388 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ecc",
"version": "2.0.0-rc.1",
- "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 228 skills, 75 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
+ "description": "Battle-tested Claude Code plugin for engineering teams — 60 agents, 229 skills, 75 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",
"author": {
"name": "Affaan Mustafa",
"url": "https://x.com/affaanmustafa"
diff --git a/AGENTS.md b/AGENTS.md
index e34717bb6..2f2c5fbf0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — Agent Instructions
-This is a **production-ready AI coding plugin** providing 60 specialized agents, 228 skills, 75 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 60 specialized agents, 229 skills, 75 commands, and automated hook workflows for software development.
**Version:** 2.0.0-rc.1
@@ -150,7 +150,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
```
agents/ — 60 specialized subagents
-skills/ — 228 workflow skills and domain knowledge
+skills/ — 229 workflow skills and domain knowledge
commands/ — 75 slash commands
hooks/ — Trigger-based automations
rules/ — Always-follow guidelines (common + per-language)
diff --git a/README.md b/README.md
index e731eb3f1..663c8fcc0 100644
--- a/README.md
+++ b/README.md
@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:
/plugin list ecc@ecc
```
-**That's it!** You now have access to 60 agents, 228 skills, and 75 legacy command shims.
+**That's it!** You now have access to 60 agents, 229 skills, and 75 legacy command shims.
### Dashboard GUI
@@ -1363,7 +1363,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.
|---------|-------------|----------|--------|
| Agents | PASS: 60 agents | PASS: 12 agents | **Claude Code leads** |
| Commands | PASS: 75 commands | PASS: 35 commands | **Claude Code leads** |
-| Skills | PASS: 228 skills | PASS: 37 skills | **Claude Code leads** |
+| Skills | PASS: 229 skills | PASS: 37 skills | **Claude Code leads** |
| Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** |
| Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** |
| MCP Servers | PASS: 14 servers | PASS: Full | **Full parity** |
@@ -1525,7 +1525,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
|---------|------------|------------|-----------|----------|----------------|
| **Agents** | 60 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 | N/A |
| **Commands** | 75 | Shared | Instruction-based | 35 | 6 prompts |
-| **Skills** | 228 | Shared | 10 (native format) | 37 | Via instructions |
+| **Skills** | 229 | Shared | 10 (native format) | 37 | Via instructions |
| **Hook Events** | 8 types | 15 types | None yet | 11 types | None |
| **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | N/A |
| **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | 1 always-on file |
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 19dfb2cf0..6ff140f9b 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**完成!** 你现在可以使用 60 个代理、228 个技能和 75 个命令。
+**完成!** 你现在可以使用 60 个代理、229 个技能和 75 个命令。
### multi-* 命令需要额外配置
diff --git a/docs/ja-JP/README.md b/docs/ja-JP/README.md
index 0a99c37ee..06c5f8f1a 100644
--- a/docs/ja-JP/README.md
+++ b/docs/ja-JP/README.md
@@ -122,12 +122,12 @@
git clone https://github.com/affaan-m/everything-claude-code.git
# 共通ルールをインストール(必須)
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
# 言語固有ルールをインストール(スタックを選択)
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/
-cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript
+cp -r everything-claude-code/rules/python ~/.claude/rules/python
+cp -r everything-claude-code/rules/golang ~/.claude/rules/golang
```
### ステップ3:使用開始
@@ -462,15 +462,15 @@ Duplicate hook file detected: ./hooks/hooks.json is already resolved to a loaded
>
> # オプション A:ユーザーレベルルール(すべてのプロジェクトに適用)
> mkdir -p ~/.claude/rules
-> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # スタックを選択
-> cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+> cp -r everything-claude-code/rules/common ~/.claude/rules/common
+> cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # スタックを選択
+> cp -r everything-claude-code/rules/python ~/.claude/rules/python
+> cp -r everything-claude-code/rules/golang ~/.claude/rules/golang
>
> # オプション B:プロジェクトレベルルール(現在のプロジェクトのみ)
> mkdir -p .claude/rules
-> cp -r everything-claude-code/rules/common/* .claude/rules/
-> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # スタックを選択
+> cp -r everything-claude-code/rules/common .claude/rules/common
+> cp -r everything-claude-code/rules/typescript .claude/rules/typescript # スタックを選択
> ```
---
@@ -487,10 +487,10 @@ git clone https://github.com/affaan-m/everything-claude-code.git
cp everything-claude-code/agents/*.md ~/.claude/agents/
# ルール(共通 + 言語固有)をコピー
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # スタックを選択
-cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
+cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # スタックを選択
+cp -r everything-claude-code/rules/python ~/.claude/rules/python
+cp -r everything-claude-code/rules/golang ~/.claude/rules/golang
# コマンドをコピー
cp everything-claude-code/commands/*.md ~/.claude/commands/
diff --git a/docs/ja-JP/skills/configure-ecc/SKILL.md b/docs/ja-JP/skills/configure-ecc/SKILL.md
index 9c289eb4e..b8b73d5fd 100644
--- a/docs/ja-JP/skills/configure-ecc/SKILL.md
+++ b/docs/ja-JP/skills/configure-ecc/SKILL.md
@@ -169,13 +169,13 @@ Options:
インストールを実行:
```bash
-# 共通ルール(rules/ にフラットコピー)
-cp -r $ECC_ROOT/rules/common/* $TARGET/rules/
+# 共通ルール
+cp -r $ECC_ROOT/rules/common $TARGET/rules/common
-# 言語固有のルール(rules/ にフラットコピー)
-cp -r $ECC_ROOT/rules/typescript/* $TARGET/rules/ # 選択された場合
-cp -r $ECC_ROOT/rules/python/* $TARGET/rules/ # 選択された場合
-cp -r $ECC_ROOT/rules/golang/* $TARGET/rules/ # 選択された場合
+# 言語固有のルール(言語別ディレクトリを保持)
+cp -r $ECC_ROOT/rules/typescript $TARGET/rules/typescript # 選択された場合
+cp -r $ECC_ROOT/rules/python $TARGET/rules/python # 選択された場合
+cp -r $ECC_ROOT/rules/golang $TARGET/rules/golang # 選択された場合
```
**重要**: ユーザーが言語固有のルールを選択したが、共通ルールを選択しなかった場合、警告します:
diff --git a/docs/ko-KR/README.md b/docs/ko-KR/README.md
index 263412402..254c3fe65 100644
--- a/docs/ko-KR/README.md
+++ b/docs/ko-KR/README.md
@@ -387,12 +387,12 @@ Claude Code v2.1+는 설치된 플러그인의 `hooks/hooks.json`을 **자동으
>
> # 옵션 A: 사용자 레벨 룰 (모든 프로젝트에 적용)
> mkdir -p ~/.claude/rules
-> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # 사용하는 스택 선택
+> cp -r everything-claude-code/rules/common ~/.claude/rules/common
+> cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # 사용하는 스택 선택
>
> # 옵션 B: 프로젝트 레벨 룰 (현재 프로젝트에만 적용)
> mkdir -p .claude/rules
-> cp -r everything-claude-code/rules/common/* .claude/rules/
+> cp -r everything-claude-code/rules/common .claude/rules/common
> ```
---
@@ -409,8 +409,8 @@ git clone https://github.com/affaan-m/everything-claude-code.git
cp everything-claude-code/agents/*.md ~/.claude/agents/
# 룰 복사 (common + 언어별)
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # 사용하는 스택 선택
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
+cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # 사용하는 스택 선택
# 커맨드 복사
cp everything-claude-code/commands/*.md ~/.claude/commands/
@@ -573,7 +573,7 @@ MCP 서버가 너무 많으면 컨텍스트를 잡아먹습니다. 각 MCP 도
cp everything-claude-code/agents/*.md ~/.claude/agents/
# 룰만
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
```
각 컴포넌트는 완전히 독립적입니다.
diff --git a/docs/pt-BR/README.md b/docs/pt-BR/README.md
index a9af42fb5..df6856525 100644
--- a/docs/pt-BR/README.md
+++ b/docs/pt-BR/README.md
@@ -342,12 +342,12 @@ Ou adicione diretamente ao seu `~/.claude/settings.json`:
>
> # Opção A: Regras no nível do usuário (aplica a todos os projetos)
> mkdir -p ~/.claude/rules
-> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # escolha sua stack
+> cp -r everything-claude-code/rules/common ~/.claude/rules/common
+> cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # escolha sua stack
>
> # Opção B: Regras no nível do projeto (aplica apenas ao projeto atual)
> mkdir -p .claude/rules
-> cp -r everything-claude-code/rules/common/* .claude/rules/
+> cp -r everything-claude-code/rules/common .claude/rules/common
> ```
---
@@ -362,8 +362,8 @@ git clone https://github.com/affaan-m/everything-claude-code.git
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Copiar regras (comuns + específicas da linguagem)
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
+cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript
# Copiar comandos
cp everything-claude-code/commands/*.md ~/.claude/commands/
diff --git a/docs/tr/README.md b/docs/tr/README.md
index dc1ecc5b5..b7ccc2004 100644
--- a/docs/tr/README.md
+++ b/docs/tr/README.md
@@ -390,7 +390,7 @@ Evet. Seçenek 2'yi (manuel kurulum) kullanın ve yalnızca ihtiyacınız olanı
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Sadece rule'lar
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
```
Her component tamamen bağımsızdır.
diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md
index 7ab620bab..134372bf6 100644
--- a/docs/zh-CN/AGENTS.md
+++ b/docs/zh-CN/AGENTS.md
@@ -1,6 +1,6 @@
# Everything Claude Code (ECC) — 智能体指令
-这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、228 项技能、75 条命令以及自动化钩子工作流,用于软件开发。
+这是一个**生产就绪的 AI 编码插件**,提供 60 个专业代理、229 项技能、75 条命令以及自动化钩子工作流,用于软件开发。
**版本:** 2.0.0-rc.1
@@ -147,7 +147,7 @@
```
agents/ — 60 个专业子代理
-skills/ — 228 个工作流技能和领域知识
+skills/ — 229 个工作流技能和领域知识
commands/ — 75 个斜杠命令
hooks/ — 基于触发的自动化
rules/ — 始终遵循的指导方针(通用 + 每种语言)
diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.md
index 4794bef1f..cf8ae7220 100644
--- a/docs/zh-CN/README.md
+++ b/docs/zh-CN/README.md
@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
-**搞定!** 你现在可以使用 60 个智能体、228 项技能和 75 个命令了。
+**搞定!** 你现在可以使用 60 个智能体、229 项技能和 75 个命令了。
***
@@ -637,16 +637,16 @@ Claude Code v2.1+ **会自动加载** 任何已安装插件中的 `hooks/hooks.j
>
> # 选项 A:用户级规则(适用于所有项目)
> mkdir -p ~/.claude/rules
-> cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # 选择您的技术栈
-> cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
-> cp -r everything-claude-code/rules/php/* ~/.claude/rules/
+> cp -r everything-claude-code/rules/common ~/.claude/rules/common
+> cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # 选择您的技术栈
+> cp -r everything-claude-code/rules/python ~/.claude/rules/python
+> cp -r everything-claude-code/rules/golang ~/.claude/rules/golang
+> cp -r everything-claude-code/rules/php ~/.claude/rules/php
>
> # 选项 B:项目级规则(仅适用于当前项目)
> mkdir -p .claude/rules
-> cp -r everything-claude-code/rules/common/* .claude/rules/
-> cp -r everything-claude-code/rules/typescript/* .claude/rules/ # 选择您的技术栈
+> cp -r everything-claude-code/rules/common .claude/rules/common
+> cp -r everything-claude-code/rules/typescript .claude/rules/typescript # 选择您的技术栈
> ```
***
@@ -663,11 +663,11 @@ git clone https://github.com/affaan-m/everything-claude-code.git
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Copy rules (common + language-specific)
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
-cp -r everything-claude-code/rules/typescript/* ~/.claude/rules/ # pick your stack
-cp -r everything-claude-code/rules/python/* ~/.claude/rules/
-cp -r everything-claude-code/rules/golang/* ~/.claude/rules/
-cp -r everything-claude-code/rules/php/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
+cp -r everything-claude-code/rules/typescript ~/.claude/rules/typescript # pick your stack
+cp -r everything-claude-code/rules/python ~/.claude/rules/python
+cp -r everything-claude-code/rules/golang ~/.claude/rules/golang
+cp -r everything-claude-code/rules/php ~/.claude/rules/php
# Copy maintained commands
cp everything-claude-code/commands/*.md ~/.claude/commands/
@@ -885,7 +885,7 @@ claude
cp everything-claude-code/agents/*.md ~/.claude/agents/
# Just rules
-cp -r everything-claude-code/rules/common/* ~/.claude/rules/
+cp -r everything-claude-code/rules/common ~/.claude/rules/common
```
每个组件都是完全独立的。
@@ -1138,7 +1138,7 @@ opencode
|---------|-------------|----------|--------|
| 智能体 | PASS: 60 个 | PASS: 12 个 | **Claude Code 领先** |
| 命令 | PASS: 75 个 | PASS: 35 个 | **Claude Code 领先** |
-| 技能 | PASS: 228 项 | PASS: 37 项 | **Claude Code 领先** |
+| 技能 | PASS: 229 项 | PASS: 37 项 | **Claude Code 领先** |
| 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** |
| 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |
| MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |
@@ -1246,7 +1246,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以
|---------|------------|------------|-----------|----------|
| **智能体** | 60 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
| **命令** | 75 | 共享 | 基于指令 | 35 |
-| **技能** | 228 | 共享 | 10 (原生格式) | 37 |
+| **技能** | 229 | 共享 | 10 (原生格式) | 37 |
| **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 |
| **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 |
| **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |
diff --git a/docs/zh-CN/skills/configure-ecc/SKILL.md b/docs/zh-CN/skills/configure-ecc/SKILL.md
index 022806529..caf6590c2 100644
--- a/docs/zh-CN/skills/configure-ecc/SKILL.md
+++ b/docs/zh-CN/skills/configure-ecc/SKILL.md
@@ -239,13 +239,13 @@ cp -R "${src%/}" "$TARGET/skills/$(basename "${src%/}")"
执行安装:
```bash
-# Common rules (flat copy into rules/)
-cp -r $ECC_ROOT/rules/common/* $TARGET/rules/
+# Common rules
+cp -r $ECC_ROOT/rules/common $TARGET/rules/common
-# Language-specific rules (flat copy into rules/)
-cp -r $ECC_ROOT/rules/typescript/* $TARGET/rules/ # if selected
-cp -r $ECC_ROOT/rules/python/* $TARGET/rules/ # if selected
-cp -r $ECC_ROOT/rules/golang/* $TARGET/rules/ # if selected
+# Language-specific rules (preserve per-language directories)
+cp -r $ECC_ROOT/rules/typescript $TARGET/rules/typescript # if selected
+cp -r $ECC_ROOT/rules/python $TARGET/rules/python # if selected
+cp -r $ECC_ROOT/rules/golang $TARGET/rules/golang # if selected
```
**重要**:如果用户选择了任何特定语言的规则但**没有**选择通用规则,警告他们:
diff --git a/manifests/install-modules.json b/manifests/install-modules.json
index 3c9f722e7..61d6ae413 100644
--- a/manifests/install-modules.json
+++ b/manifests/install-modules.json
@@ -199,7 +199,8 @@
"skills/database-migrations",
"skills/jpa-patterns",
"skills/mysql-patterns",
- "skills/postgres-patterns"
+ "skills/postgres-patterns",
+ "skills/prisma-patterns"
],
"targets": [
"claude",
diff --git a/package.json b/package.json
index 501d337d6..098c4ada4 100644
--- a/package.json
+++ b/package.json
@@ -215,6 +215,7 @@
"skills/perl-testing/",
"skills/plankton-code-quality/",
"skills/postgres-patterns/",
+ "skills/prisma-patterns/",
"skills/product-capability/",
"skills/production-audit/",
"skills/production-scheduling/",
diff --git a/rules/ruby/hooks.md b/rules/ruby/hooks.md
index 0415fe612..1ec61d86f 100644
--- a/rules/ruby/hooks.md
+++ b/rules/ruby/hooks.md
@@ -15,7 +15,7 @@ paths:
Configure project-local hooks to prefer binstubs and checked-in tooling:
- **RuboCop**: run `bundle exec rubocop -A <file>` or the project's safer formatter command after Ruby edits.
-- **Brakeman**: run `bundle exec brakeman --no-pager` after security-sensitive Rails changes.
+- **Brakeman**: run `bundle exec brakeman --no-progress` after security-sensitive Rails changes.
- **Tests**: run the narrowest matching `bin/rails test ...` or `bundle exec rspec ...` command for touched files.
- **Bundler audit**: run `bundle exec bundle-audit check --update` when `Gemfile` or `Gemfile.lock` changes and the project has bundler-audit installed.
@@ -29,7 +29,7 @@ Configure project-local hooks to prefer binstubs and checked-in tooling:
```bash
bundle exec rubocop
-bundle exec brakeman --no-pager
+bundle exec brakeman --no-progress
bin/rails test
bundle exec rspec
```
diff --git a/rules/ruby/security.md b/rules/ruby/security.md
index 1ecf0645b..4821c2c07 100644
--- a/rules/ruby/security.md
+++ b/rules/ruby/security.md
@@ -34,8 +34,8 @@ paths:
- Run dependency checks when the lockfile changes:
```bash
-bundle audit check --update
-bundle exec brakeman --no-pager
+bundle exec bundle-audit check --update
+bundle exec brakeman --no-progress
```
- Review new gems for maintainer activity, native extension risk, transitive dependencies, and whether the same behavior can be implemented with Rails core.
diff --git a/scripts/hooks/config-protection.js b/scripts/hooks/config-protection.js
index 8592542ee..625da3b71 100644
--- a/scripts/hooks/config-protection.js
+++ b/scripts/hooks/config-protection.js
@@ -7,12 +7,13 @@
* the actual code. This hook steers the agent back to fixing the source.
*
* Exit codes:
- * 0 = allow (not a config file)
- * 2 = block (config file modification attempted)
+ * 0 = allow (not a config file, or first-time creation of one)
+ * 2 = block (existing config file modification attempted)
*/
'use strict';
+const fs = require('fs');
const path = require('path');
const MAX_STDIN = 1024 * 1024;
@@ -58,7 +59,7 @@ const PROTECTED_FILES = new Set([
'.stylelintrc.yml',
'.markdownlint.json',
'.markdownlint.yaml',
- '.markdownlintrc',
+ '.markdownlintrc'
]);
function parseInput(inputOrRaw) {
@@ -94,13 +95,41 @@ function run(inputOrRaw, options = {}) {
const basename = path.basename(filePath);
if (PROTECTED_FILES.has(basename)) {
+ // Allow first-time creation — there's no existing config to weaken.
+ // The hook's purpose is blocking modifications; writing a brand-new
+ // config file in a project that has none is a legitimate bootstrap
+ // path (e.g. scaffolding ESLint into a fresh repo).
+ //
+ // Fail closed on any stat error other than ENOENT. Use lstatSync so a
+ // symlink at the protected path is treated as present even if its target
+ // is missing — a dangling symlink at e.g. .eslintrc.js still represents
+ // an existing config entry that an agent should not silently replace.
+ // fs.existsSync would swallow EACCES/EPERM as false; lstatSync exposes
+ // the error code so we can treat only genuine "path not found" (ENOENT)
+ // as absent.
+ let exists = true;
+ try {
+ fs.lstatSync(filePath);
+ // lstat succeeded — something (file, dir, or symlink) exists here.
+ } catch (err) {
+ if (err && err.code === 'ENOENT') {
+ exists = false;
+ }
+ // Any other error (EACCES, EPERM, ELOOP, etc.) leaves exists=true
+ // so the guard is never silently weakened.
+ }
+
+ if (!exists) {
+ return { exitCode: 0 };
+ }
+
return {
exitCode: 2,
stderr:
`BLOCKED: Modifying ${basename} is not allowed. ` +
'Fix the source code to satisfy linter/formatter rules instead of ' +
'weakening the config. If this is a legitimate config change, ' +
- 'disable the config-protection hook temporarily.',
+ 'disable the config-protection hook temporarily.'
};
}
@@ -125,7 +154,7 @@ process.stdin.on('data', chunk => {
process.stdin.on('end', () => {
const result = run(raw, {
truncated,
- maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN,
+ maxStdin: Number(process.env.ECC_HOOK_INPUT_MAX_BYTES) || MAX_STDIN
});
if (result.stderr) {
diff --git a/scripts/hooks/cost-tracker.js b/scripts/hooks/cost-tracker.js
index a3f2f8962..291345cc0 100755
--- a/scripts/hooks/cost-tracker.js
+++ b/scripts/hooks/cost-tracker.js
@@ -1,63 +1,157 @@
#!/usr/bin/env node
/**
- * Cost Tracker Hook
+ * Cost Tracker Hook (v2)
*
- * Appends lightweight session usage metrics to ~/.claude/metrics/costs.jsonl.
+ * Reads transcript_path from Stop hook stdin, sums usage across all
+ * assistant turns in the session JSONL, and appends one row to
+ * ~/.claude/metrics/costs.jsonl.
+ *
+ * Stop hook stdin payload: { session_id, transcript_path, cwd, hook_event_name, ... }
+ * The Stop payload does NOT include `usage` or `model` directly. The previous
+ * version of this hook expected those fields and silently produced zero-filled
+ * rows (verified: 2,340 rows captured with 0.0% non-zero token rate over 52
+ * days). The fix is to read the transcript file Claude Code already passes us.
+ *
+ * JSONL assistant entry shape (per Claude Code):
+ * { type: "assistant", message: { model, usage: { input_tokens, output_tokens,
+ * cache_creation_input_tokens, cache_read_input_tokens } } }
+ *
+ * Cumulative behavior: Stop fires per assistant response, not per session.
+ * Each row therefore represents the cumulative session total up to that point.
+ * To get per-session cost, take the last row per session_id. To get per-day
+ * spend, aggregate.
*/
'use strict';
+const fs = require('fs');
const path = require('path');
const { ensureDir, appendFile, getClaudeDir } = require('../lib/utils');
-const { estimateCost } = require('../lib/cost-estimate');
const { sanitizeSessionId } = require('../lib/session-bridge');
-const MAX_STDIN = 1024 * 1024;
-let raw = '';
+// Approximate per-1M-token billing rates (USD).
+// Cache creation: 1.25x input rate. Cache read: 0.1x input rate.
+const RATE_TABLE = {
+ haiku: { in: 0.80, out: 4.0, cacheWrite: 1.00, cacheRead: 0.08 },
+ sonnet: { in: 3.00, out: 15.0, cacheWrite: 3.75, cacheRead: 0.30 },
+ opus: { in: 15.00, out: 75.0, cacheWrite: 18.75, cacheRead: 1.50 }
+};
-function toNumber(value) {
- const n = Number(value);
+function getRates(model) {
+ const m = String(model || '').toLowerCase();
+ if (m.includes('haiku')) return RATE_TABLE.haiku;
+ if (m.includes('opus')) return RATE_TABLE.opus;
+ return RATE_TABLE.sonnet;
+}
+
+function toNumber(v) {
+ const n = Number(v);
return Number.isFinite(n) ? n : 0;
}
+/**
+ * Scan the session JSONL and sum token usage across all assistant turns.
+ * Returns { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, model }
+ * or null on read failure.
+ */
+function sumUsageFromTranscript(transcriptPath) {
+ let content;
+ try {
+ content = fs.readFileSync(transcriptPath, 'utf8');
+ } catch {
+ return null;
+ }
+
+ let inputTokens = 0;
+ let outputTokens = 0;
+ let cacheWriteTokens = 0;
+ let cacheReadTokens = 0;
+ let model = 'unknown';
+
+ for (const line of content.split('\n')) {
+ if (!line.trim()) continue;
+ let entry;
+ try { entry = JSON.parse(line); } catch { continue; }
+
+ if (entry.type !== 'assistant') continue;
+ const msg = entry.message;
+ if (!msg || !msg.usage) continue;
+
+ const u = msg.usage;
+ inputTokens += toNumber(u.input_tokens);
+ outputTokens += toNumber(u.output_tokens);
+ cacheWriteTokens += toNumber(u.cache_creation_input_tokens);
+ cacheReadTokens += toNumber(u.cache_read_input_tokens);
+
+ if (msg.model && msg.model !== 'unknown') model = msg.model;
+ }
+
+ return { inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens, model };
+}
+
+const MAX_STDIN = 64 * 1024;
+let raw = '';
+
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => {
- if (raw.length < MAX_STDIN) {
- const remaining = MAX_STDIN - raw.length;
- raw += chunk.substring(0, remaining);
- }
+ if (raw.length < MAX_STDIN) raw += chunk.substring(0, MAX_STDIN - raw.length);
});
process.stdin.on('end', () => {
try {
const input = raw.trim() ? JSON.parse(raw) : {};
- const usage = input.usage || input.token_usage || {};
- const inputTokens = toNumber(usage.input_tokens || usage.prompt_tokens || 0);
- const outputTokens = toNumber(usage.output_tokens || usage.completion_tokens || 0);
- const model = String(input.model || input._cursor?.model || process.env.CLAUDE_MODEL || 'unknown');
+ const transcriptPath = (typeof input.transcript_path === 'string' && input.transcript_path)
+ ? input.transcript_path
+ : process.env.CLAUDE_TRANSCRIPT_PATH || null;
+
const sessionId =
sanitizeSessionId(input.session_id) ||
sanitizeSessionId(process.env.ECC_SESSION_ID) ||
sanitizeSessionId(process.env.CLAUDE_SESSION_ID) ||
'default';
+ let usageTotals = null;
+ if (transcriptPath && fs.existsSync(transcriptPath)) {
+ usageTotals = sumUsageFromTranscript(transcriptPath);
+ }
+
+ const {
+ inputTokens = 0,
+ outputTokens = 0,
+ cacheWriteTokens = 0,
+ cacheReadTokens = 0,
+ model = 'unknown'
+ } = usageTotals || {};
+
+ const rates = getRates(model);
+ const estimatedCostUsd = Math.round((
+ (inputTokens / 1e6) * rates.in +
+ (outputTokens / 1e6) * rates.out +
+ (cacheWriteTokens / 1e6) * rates.cacheWrite +
+ (cacheReadTokens / 1e6) * rates.cacheRead
+ ) * 1e6) / 1e6;
+
const metricsDir = path.join(getClaudeDir(), 'metrics');
ensureDir(metricsDir);
const row = {
- timestamp: new Date().toISOString(),
- session_id: sessionId,
+ timestamp: new Date().toISOString(),
+ session_id: sessionId,
+ transcript_path: transcriptPath || '',
model,
- input_tokens: inputTokens,
- output_tokens: outputTokens,
- estimated_cost_usd: estimateCost(model, inputTokens, outputTokens)
+ input_tokens: inputTokens,
+ output_tokens: outputTokens,
+ cache_write_tokens: cacheWriteTokens,
+ cache_read_tokens: cacheReadTokens,
+ estimated_cost_usd: estimatedCostUsd
};
appendFile(path.join(metricsDir, 'costs.jsonl'), `${JSON.stringify(row)}\n`);
} catch {
- // Keep hook non-blocking.
+ // Non-blocking — never fail the Stop hook.
}
+ // Pass stdin through (required by ECC hook convention).
process.stdout.write(raw);
});
diff --git a/scripts/hooks/pre-bash-dev-server-block.js b/scripts/hooks/pre-bash-dev-server-block.js
index 9c0861b8a..cd663fa70 100755
--- a/scripts/hooks/pre-bash-dev-server-block.js
+++ b/scripts/hooks/pre-bash-dev-server-block.js
@@ -4,6 +4,10 @@
const MAX_STDIN = 1024 * 1024;
const path = require('path');
const { splitShellSegments } = require('../lib/shell-split');
+const {
+ extractCommandSubstitutions,
+ extractSubshellGroups
+} = require('../lib/shell-substitution');
const DEV_COMMAND_WORDS = new Set([
'npm',
@@ -123,6 +127,8 @@ function getLeadingCommandWord(segment) {
continue;
}
+ if (token === '{' || token === '}') continue;
+
if (/^[A-Za-z_][A-Za-z0-9_]*=.*/.test(token)) continue;
const normalizedToken = normalizeCommandWord(token);
@@ -154,23 +160,55 @@ process.stdin.on('data', chunk => {
}
});
+const TMUX_LAUNCHER = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
+const DEV_PATTERN = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn(?:\s+run)?\s+dev|bun(?:\s+run)?\s+dev)\b/;
+
+/**
+ * Collect every command-line segment we should evaluate. Returns the top-level
+ * segments first, then segments harvested from `$(...)` / backtick command
+ * substitutions and plain `(...)` subshell groups, recursively.
+ *
+ * Without this expansion the leading-command and dev-pattern check below only
+ * sees the outermost command, so wrappers like `$(npm run dev)` and
+ * `(npm run dev)` (which still spawn a dev server) sneak past.
+ */
+function collectCheckSegments(cmd) {
+ const segments = [...splitShellSegments(cmd)];
+ const queue = [cmd];
+ const seen = new Set();
+
+ while (queue.length) {
+ const current = queue.shift();
+ if (seen.has(current)) continue;
+ seen.add(current);
+
+ for (const body of extractCommandSubstitutions(current)) {
+ for (const seg of splitShellSegments(body)) segments.push(seg);
+ queue.push(body);
+ }
+ for (const body of extractSubshellGroups(current)) {
+ for (const seg of splitShellSegments(body)) segments.push(seg);
+ queue.push(body);
+ }
+ }
+
+ return segments;
+}
+
+function isBlockedDevSegment(segment) {
+ const commandWord = getLeadingCommandWord(segment);
+ if (!commandWord || !DEV_COMMAND_WORDS.has(commandWord)) return false;
+ return DEV_PATTERN.test(segment) && !TMUX_LAUNCHER.test(segment);
+}
+
process.stdin.on('end', () => {
try {
const input = JSON.parse(raw);
const cmd = String(input.tool_input?.command || '');
if (process.platform !== 'win32') {
- const segments = splitShellSegments(cmd);
- const tmuxLauncher = /^\s*tmux\s+(new|new-session|new-window|split-window)\b/;
- const devPattern = /\b(npm\s+run\s+dev|pnpm(?:\s+run)?\s+dev|yarn\s+dev|bun\s+run\s+dev)\b/;
-
- const hasBlockedDev = segments.some(segment => {
- const commandWord = getLeadingCommandWord(segment);
- if (!commandWord || !DEV_COMMAND_WORDS.has(commandWord)) {
- return false;
- }
- return devPattern.test(segment) && !tmuxLauncher.test(segment);
- });
+ const segments = collectCheckSegments(cmd);
+ const hasBlockedDev = segments.some(isBlockedDevSegment);
if (hasBlockedDev) {
console.error('[Hook] BLOCKED: Dev server must run in tmux for log access');
diff --git a/scripts/hooks/suggest-compact.js b/scripts/hooks/suggest-compact.js
index be3f2e795..0e9d5e66a 100644
--- a/scripts/hooks/suggest-compact.js
+++ b/scripts/hooks/suggest-compact.js
@@ -19,7 +19,8 @@ const {
getTempDir,
writeFile,
readStdinJson,
- log
+ log,
+ output
} = require('../lib/utils');
async function resolveSessionId() {
@@ -77,14 +78,25 @@ async function main() {
writeFile(counterFile, String(count));
}
- // Suggest compact after threshold tool calls
+ // Suggest compact after threshold tool calls.
+ //
+ // log() writes to stderr (debug log). Per the Claude Code hooks guide,
+ // non-blocking PreToolUse stderr (exit 0) is only written to the debug log;
+ // it does not reach the model. To inject a user-facing suggestion without
+ // blocking the tool call, emit structured JSON to stdout with
+ // hookSpecificOutput.additionalContext — the documented mechanism for
+ // PreToolUse hooks to add context to the next model turn.
if (count === threshold) {
- log(`[StrategicCompact] ${threshold} tool calls reached - consider /compact if transitioning phases`);
+ const msg = `[StrategicCompact] ${threshold} tool calls reached - consider /compact if transitioning phases`;
+ log(msg);
+ output({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: msg } });
}
// Suggest at regular intervals after threshold (every 25 calls from threshold)
if (count > threshold && (count - threshold) % 25 === 0) {
- log(`[StrategicCompact] ${count} tool calls - good checkpoint for /compact if context is stale`);
+ const msg = `[StrategicCompact] ${count} tool calls - good checkpoint for /compact if context is stale`;
+ log(msg);
+ output({ hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: msg } });
}
process.exit(0);
diff --git a/scripts/lib/shell-substitution.js b/scripts/lib/shell-substitution.js
new file mode 100644
index 000000000..dd5d6c74f
--- /dev/null
+++ b/scripts/lib/shell-substitution.js
@@ -0,0 +1,246 @@
+'use strict';
+
+/**
+ * Extract executable command-substitution bodies from a shell line.
+ *
+ * Single quotes are literal, so substitutions inside them are ignored;
+ * double quotes still permit substitutions, so those bodies are scanned
+ * before quoted text is stripped. Returns each substitution body plus
+ * any nested substitutions discovered recursively.
+ *
+ * Originally introduced in scripts/hooks/gateguard-fact-force.js
+ * (PR #1853 round 2). Extracted to a shared lib so other PreToolUse
+ * hooks that need the same "scan inside `$(...)` and backticks"
+ * behavior can reuse it without duplicating the parser.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+function extractCommandSubstitutions(input) {
+ const source = String(input || '');
+ const substitutions = [];
+ let inSingle = false;
+ let inDouble = false;
+
+ for (let i = 0; i < source.length; i++) {
+ const ch = source[i];
+ const prev = source[i - 1];
+
+ if (ch === '\\' && !inSingle) {
+ i += 1;
+ continue;
+ }
+
+ if (ch === "'" && !inDouble && prev !== '\\') {
+ inSingle = !inSingle;
+ continue;
+ }
+
+ if (ch === '"' && !inSingle && prev !== '\\') {
+ inDouble = !inDouble;
+ continue;
+ }
+
+ if (inSingle) {
+ continue;
+ }
+
+ if (ch === '`') {
+ let body = '';
+ i += 1;
+ while (i < source.length) {
+ const inner = source[i];
+ if (inner === '\\') {
+ body += inner;
+ if (i + 1 < source.length) {
+ body += source[i + 1];
+ i += 2;
+ continue;
+ }
+ }
+ if (inner === '`') {
+ break;
+ }
+ body += inner;
+ i += 1;
+ }
+ if (body.trim()) {
+ substitutions.push(body);
+ substitutions.push(...extractCommandSubstitutions(body));
+ }
+ continue;
+ }
+
+ if (ch === '$' && source[i + 1] === '(') {
+ let depth = 1;
+ let body = '';
+ let bodyInSingle = false;
+ let bodyInDouble = false;
+ i += 2;
+ while (i < source.length && depth > 0) {
+ const inner = source[i];
+ const innerPrev = source[i - 1];
+ if (inner === '\\' && !bodyInSingle) {
+ body += inner;
+ if (i + 1 < source.length) {
+ body += source[i + 1];
+ i += 2;
+ continue;
+ }
+ }
+ if (inner === "'" && !bodyInDouble && innerPrev !== '\\') {
+ bodyInSingle = !bodyInSingle;
+ } else if (inner === '"' && !bodyInSingle && innerPrev !== '\\') {
+ bodyInDouble = !bodyInDouble;
+ } else if (!bodyInSingle && !bodyInDouble) {
+ if (inner === '(') {
+ depth += 1;
+ } else if (inner === ')') {
+ depth -= 1;
+ if (depth === 0) {
+ break;
+ }
+ }
+ }
+ body += inner;
+ i += 1;
+ }
+ if (body.trim()) {
+ substitutions.push(body);
+ substitutions.push(...extractCommandSubstitutions(body));
+ }
+ }
+ }
+
+ return substitutions;
+}
+
+/**
+ * Extract bodies of plain `(...)` subshell groups.
+ *
+ * Bash treats `(npm run dev)` as a subshell that executes its contents, but
+ * the regex-light segment splitters used by our PreToolUse hooks don't peer
+ * inside those parens. This helper finds top-level `(...)` groups (skipping
+ * `$(...)` command substitutions and backticks, which `extractCommandSubstitutions`
+ * already covers) and returns each body, recursing for nested groups.
+ *
+ * Quote semantics:
+ * - Single quotes are literal: `'( ... )'` is a string, not a subshell.
+ * - Double quotes are literal *for parens*: `"( ... )"` is a string too —
+ * bash only honors `$( )` inside double quotes, not bare `( )`.
+ *
+ * @param {string} input
+ * @returns {string[]}
+ */
+function extractSubshellGroups(input) {
+ const source = String(input || '');
+ const groups = [];
+ let inSingle = false;
+ let inDouble = false;
+
+ for (let i = 0; i < source.length; i++) {
+ const ch = source[i];
+ const prev = source[i - 1];
+
+ if (ch === '\\' && !inSingle) {
+ i += 1;
+ continue;
+ }
+
+ if (ch === "'" && !inDouble && prev !== '\\') {
+ inSingle = !inSingle;
+ continue;
+ }
+
+ if (ch === '"' && !inSingle && prev !== '\\') {
+ inDouble = !inDouble;
+ continue;
+ }
+
+ if (inSingle || inDouble) {
+ continue;
+ }
+
+ if (ch === '$' && source[i + 1] === '(') {
+ let depth = 1;
+ let skipInSingle = false;
+ let skipInDouble = false;
+ i += 2;
+ while (i < source.length && depth > 0) {
+ const inner = source[i];
+ const innerPrev = source[i - 1];
+ if (inner === '\\' && !skipInSingle) {
+ i += 2;
+ continue;
+ }
+ if (inner === "'" && !skipInDouble && innerPrev !== '\\') {
+ skipInSingle = !skipInSingle;
+ } else if (inner === '"' && !skipInSingle && innerPrev !== '\\') {
+ skipInDouble = !skipInDouble;
+ } else if (!skipInSingle && !skipInDouble) {
+ if (inner === '(') depth += 1;
+ else if (inner === ')') depth -= 1;
+ }
+ i += 1;
+ }
+ i -= 1;
+ continue;
+ }
+
+ if (ch === '`') {
+ i += 1;
+ while (i < source.length && source[i] !== '`') {
+ if (source[i] === '\\' && i + 1 < source.length) {
+ i += 2;
+ continue;
+ }
+ i += 1;
+ }
+ continue;
+ }
+
+ if (ch === '(') {
+ let depth = 1;
+ let body = '';
+ let bodyInSingle = false;
+ let bodyInDouble = false;
+ i += 1;
+ while (i < source.length && depth > 0) {
+ const inner = source[i];
+ const innerPrev = source[i - 1];
+ if (inner === '\\' && !bodyInSingle) {
+ body += inner;
+ if (i + 1 < source.length) {
+ body += source[i + 1];
+ i += 2;
+ continue;
+ }
+ }
+ if (inner === "'" && !bodyInDouble && innerPrev !== '\\') {
+ bodyInSingle = !bodyInSingle;
+ } else if (inner === '"' && !bodyInSingle && innerPrev !== '\\') {
+ bodyInDouble = !bodyInDouble;
+ } else if (!bodyInSingle && !bodyInDouble) {
+ if (inner === '(') {
+ depth += 1;
+ } else if (inner === ')') {
+ depth -= 1;
+ if (depth === 0) {
+ break;
+ }
+ }
+ }
+ body += inner;
+ i += 1;
+ }
+ if (body.trim()) {
+ groups.push(body);
+ groups.push(...extractSubshellGroups(body));
+ }
+ }
+ }
+
+ return groups;
+}
+
+module.exports = { extractCommandSubstitutions, extractSubshellGroups };
diff --git a/skills/configure-ecc/SKILL.md b/skills/configure-ecc/SKILL.md
index 50f9ad867..679ae7fde 100644
--- a/skills/configure-ecc/SKILL.md
+++ b/skills/configure-ecc/SKILL.md
@@ -234,13 +234,13 @@ Options:
Execute installation:
```bash
-# Common rules (flat copy into rules/)
-cp -r $ECC_ROOT/rules/common/* $TARGET/rules/
+# Common rules
+cp -r $ECC_ROOT/rules/common $TARGET/rules/common
-# Language-specific rules (flat copy into rules/)
-cp -r $ECC_ROOT/rules/typescript/* $TARGET/rules/ # if selected
-cp -r $ECC_ROOT/rules/python/* $TARGET/rules/ # if selected
-cp -r $ECC_ROOT/rules/golang/* $TARGET/rules/ # if selected
+# Language-specific rules (preserve per-language directories)
+cp -r $ECC_ROOT/rules/typescript $TARGET/rules/typescript # if selected
+cp -r $ECC_ROOT/rules/python $TARGET/rules/python # if selected
+cp -r $ECC_ROOT/rules/golang $TARGET/rules/golang # if selected
```
**Important**: If the user selects any language-specific rules but NOT common rules, warn them:
diff --git a/skills/prisma-patterns/SKILL.md b/skills/prisma-patterns/SKILL.md
new file mode 100644
index 000000000..8524ec40d
--- /dev/null
+++ b/skills/prisma-patterns/SKILL.md
@@ -0,0 +1,371 @@
+---
+name: prisma-patterns
+description: Prisma ORM patterns for TypeScript backends — schema design, query optimization, transactions, pagination, and critical traps like updateMany returning count not records, $transaction timeouts, migrate dev resetting the DB, @updatedAt skipped on bulk writes, and serverless connection exhaustion.
+origin: ECC
+---
+
+# Prisma Patterns
+
+Production patterns and non-obvious traps for Prisma ORM in TypeScript backends.
+Tested against Prisma 5.x and 6.x. Some behaviors differ from Prisma 4.
+
+Check the Prisma version before applying version-specific patterns:
+
+```bash
+npx prisma --version
+```
+
+Prisma 5 introduced `relationJoins`, which can load relations via JOIN rather than separate queries depending on query strategy and configuration. The `omit` field modifier and `prisma.$extends` Client Extensions API were also added. Note: `relationJoins` can cause row explosion on large 1:N relations or deep nested `include` — benchmark both approaches when relations may return many rows per parent.
+
+## When to Activate
+
+- Designing or modifying Prisma schema models and relations
+- Writing queries, transactions, or pagination logic
+- Using `updateMany`, `deleteMany`, or any bulk operation
+- Running or planning database migrations
+- Deploying to serverless environments (Vercel, Lambda, Cloudflare Workers)
+- Implementing soft delete or multi-tenant row filtering
+
+## Core Concepts
+
+### ID Strategy
+
+| Strategy | Use When | Avoid When |
+|---|---|---|
+| `@default(cuid())` | Default choice — URL-safe, sortable, no collisions | Sequential IDs needed for external systems |
+| `@default(uuid())` | Interoperability with non-Prisma systems required | High-write tables (random UUIDs fragment B-tree indexes) |
+| `@default(autoincrement())` | Internal join tables, audit logs | Public-facing IDs (exposes record count) |
+
+### Schema Defaults
+
+```prisma
+model User {
+ id String @id @default(cuid())
+ email String @unique // @unique already creates an index — no @@index needed
+ name String
+ role Role @default(USER)
+ posts Post[]
+ createdAt DateTime @default(now())
+ updatedAt DateTime @updatedAt
+ deletedAt DateTime?
+
+ @@index([createdAt])
+ @@index([deletedAt, createdAt]) // composite for soft-delete + sort queries
+}
+```
+
+- Add `@@index` on every foreign key and column used in `WHERE` or `ORDER BY`.
+- Declare `deletedAt DateTime?` upfront when soft delete is a foreseeable requirement — adding it later requires a migration on a live table.
+- `updatedAt @updatedAt` is set automatically by Prisma on `update` and `upsert` only (see Anti-Patterns for bulk update trap).
+
+### `include` vs `select`
+
+| | `include` | `select` |
+|---|---|---|
+| Returns | All scalar fields + specified relations | Only specified fields |
+| Use when | You need most fields plus a relation | Hot paths, large tables, avoiding over-fetch |
+| Performance | May over-fetch on wide tables | Minimal payload, faster on large datasets |
+| Prisma 5 note | Uses JOIN by default (`relationJoins`) | Same |
+
+```ts
+// include — all columns + relation
+const user = await prisma.user.findUnique({
+ where: { id },
+ include: { posts: { select: { id: true, title: true } } },
+});
+
+// select — explicit allowlist
+const user = await prisma.user.findUnique({
+ where: { id },
+ select: { id: true, email: true, name: true },
+});
+```
+
+Never return raw Prisma entities from API responses — map to response DTOs to control exposed fields:
+
+```ts
+// BAD: leaks passwordHash, deletedAt, internal fields
+return await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// GOOD: explicit DTO mapping
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+return { id: user.id, name: user.name, email: user.email };
+```
+
+### Transaction Form Selection
+
+| Situation | Use |
+|---|---|
+| Independent operations, no inter-dependency | Array form |
+| Later step depends on earlier result | Interactive form |
+| External calls (email, HTTP) involved | Outside transaction entirely |
+
+```ts
+// Array form — batched in one round trip
+const [user, post] = await prisma.$transaction([
+ prisma.user.update({ where: { id }, data: { name } }),
+ prisma.post.create({ data: { title, authorId: id } }),
+]);
+
+// Interactive form — use tx client only, never the outer prisma client
+const post = await prisma.$transaction(async (tx) => {
+ const user = await tx.user.findUniqueOrThrow({ where: { id } });
+ if (user.role !== 'ADMIN') throw new Error('Forbidden');
+ return tx.post.create({ data: { title, authorId: user.id } });
+});
+```
+
+### PrismaClient Singleton
+
+Each `PrismaClient` instance opens its own connection pool. Instantiate once.
+
+```ts
+// lib/prisma.ts
+import { PrismaClient } from '@prisma/client';
+
+const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
+
+export const prisma =
+ globalForPrisma.prisma ??
+ new PrismaClient({
+ log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
+ });
+
+if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
+```
+
+The `globalThis` pattern prevents duplicate instances during hot reload (Next.js, nodemon, ts-node-dev).
+
+### N+1 Problem
+
+Loading relations inside a loop issues one query per row.
+
+```ts
+// BAD: N+1 — one extra query per user
+const users = await prisma.user.findMany();
+for (const user of users) {
+ const posts = await prisma.post.findMany({ where: { authorId: user.id } });
+}
+
+// GOOD: single query
+const users = await prisma.user.findMany({ include: { posts: true } });
+```
+
+With Prisma 5+ `relationJoins`, the `include` form uses a single JOIN. On large 1:N sets this may increase result set size — benchmark both approaches if the relation can return many rows per parent.
+
+## Code Examples
+
+### Cursor Pagination (preferred for feeds and large datasets)
+
+```ts
+async function getPosts(cursor?: string, limit = 20) {
+ const items = await prisma.post.findMany({
+ where: { published: true },
+ orderBy: [
+ { createdAt: 'desc' },
+ { id: 'desc' }, // secondary sort prevents unstable pagination on duplicate timestamps
+ ],
+ take: limit + 1,
+ ...(cursor && { cursor: { id: cursor }, skip: 1 }),
+ });
+
+ const hasNextPage = items.length > limit;
+ if (hasNextPage) items.pop();
+
+ return { items, nextCursor: hasNextPage ? items[items.length - 1].id : null };
+}
+```
+
+Fetch `limit + 1` and pop — canonical way to detect `hasNextPage` without an extra count query. Always include a unique field (e.g. `id`) as a secondary `orderBy` to prevent unstable pagination when multiple rows share the same timestamp. Use offset pagination only when users need to jump to arbitrary pages (admin tables).
+
+### Soft Delete
+
+```ts
+// Always filter explicitly — do not rely on middleware (hides behavior, hard to debug)
+const activeUsers = await prisma.user.findMany({ where: { deletedAt: null } });
+
+await prisma.user.update({ where: { id }, data: { deletedAt: new Date() } });
+await prisma.user.update({ where: { id }, data: { deletedAt: null } }); // restore
+```
+
+### Error Handling
+
+```ts
+import { Prisma } from '@prisma/client';
+
+try {
+ await prisma.user.create({ data: { email } });
+} catch (e) {
+ if (e instanceof Prisma.PrismaClientKnownRequestError) {
+ if (e.code === 'P2002') throw new ConflictError('Email already exists');
+ if (e.code === 'P2025') throw new NotFoundError('Record not found');
+ if (e.code === 'P2003') throw new BadRequestError('Referenced record does not exist');
+ }
+ throw e;
+}
+```
+
+Common codes: `P2002` unique violation · `P2025` not found · `P2003` foreign key violation.
+
+Catch at the service boundary and translate to domain errors. Never expose raw Prisma messages to API consumers.
+
+### Connection Pool — Serverless
+
+Embed connection params directly in `DATABASE_URL` — string concatenation breaks if the URL already has query parameters (e.g. `?schema=public`):
+
+```bash
+# .env — preferred: embed params in the URL
+DATABASE_URL="postgresql://user:pass@host/db?connection_limit=1&pool_timeout=20"
+
+# With an external pooler (PgBouncer, Supabase pooler)
+DATABASE_URL="postgresql://user:pass@host/db?pgbouncer=true&connection_limit=1"
+```
+
+```ts
+// Vercel, AWS Lambda, and similar serverless runtimes: cap pool to 1 per instance
+// connection_limit and pool_timeout are controlled via DATABASE_URL
+const prisma = new PrismaClient();
+```
+
+## Anti-Patterns
+
+### `updateMany` returns a count, not records
+
+```ts
+// BAD: result is { count: 2 } — users[0] is undefined
+const users = await prisma.user.updateMany({ where: { role: 'GUEST' }, data: { role: 'USER' } });
+
+// GOOD: capture IDs first, then update, then fetch only the affected rows
+const targets = await prisma.user.findMany({
+ where: { role: 'GUEST' },
+ select: { id: true },
+});
+const ids = targets.map((u) => u.id);
+await prisma.user.updateMany({ where: { id: { in: ids } }, data: { role: 'USER' } });
+const updated = await prisma.user.findMany({ where: { id: { in: ids } } });
+```
+
+Same applies to `deleteMany` — returns `{ count: n }`, never the deleted rows.
+
+### `$transaction` interactive form times out after 5 seconds
+
+```ts
+// BAD: external call inside transaction exceeds 5s default → "Transaction already closed"
+await prisma.$transaction(async (tx) => {
+ const user = await tx.user.findUniqueOrThrow({ where: { id } });
+ await sendWelcomeEmail(user.email); // external call
+ await tx.user.update({ where: { id }, data: { emailSent: true } });
+});
+
+// GOOD: external calls outside the transaction
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+await sendWelcomeEmail(user.email);
+await prisma.user.update({ where: { id }, data: { emailSent: true } });
+
+// Only raise timeout when bulk processing genuinely needs it
+await prisma.$transaction(async (tx) => { ... }, { timeout: 30_000 });
+```
+
+### `migrate dev` can reset the database
+
+`migrate dev` detects schema drift and may prompt to reset the DB, dropping all data.
+
+```bash
+# NEVER on shared dev, staging, or production
+npx prisma migrate dev --name add_column
+
+# Safe everywhere except local solo dev
+npx prisma migrate deploy
+
+# Check drift without applying
+npx prisma migrate diff \
+ --from-migrations ./prisma/migrations \
+ --to-schema-datamodel ./prisma/schema.prisma \
+ --shadow-database-url "$SHADOW_DATABASE_URL"
+```
+
+### Manually editing a migration file breaks future deploys
+
+Prisma checksums every migration file. Editing after apply causes `P3006 checksum mismatch` on every environment where the original already ran. Create a new migration instead.
+
+### Breaking schema changes require multi-step migration
+
+Adding `NOT NULL` to an existing column or renaming a column in one migration will lock the table or drop data. Use expand-and-contract:
+
+```bash
+# Step 1: create migration locally, then deploy
+npx prisma migrate dev --name add_new_column # local only
+npx prisma migrate deploy # staging / production
+```
+
+```ts
+// Step 2: backfill data (run in a script or migration job, not in the shell)
+await prisma.user.updateMany({ data: { newColumn: derivedValue } });
+```
+
+```bash
+# Step 3: create the NOT NULL constraint migration locally, then deploy
+npx prisma migrate dev --name make_new_column_required # local only
+npx prisma migrate deploy # staging / production
+```
+
+### `@updatedAt` does not fire on `updateMany`
+
+`@updatedAt` is set automatically only on `update` and `upsert`. Bulk writes leave it stale.
+
+```ts
+// BAD: updatedAt stays at its old value
+await prisma.post.updateMany({ where: { authorId }, data: { published: true } });
+
+// GOOD
+await prisma.post.updateMany({
+ where: { authorId },
+ data: { published: true, updatedAt: new Date() },
+});
+```
+
+### Soft delete + `findUniqueOrThrow` leaks deleted records
+
+`findUniqueOrThrow` throws `P2025` only when the row does not exist in the DB. Soft-deleted rows still exist and are returned without error.
+
+`findUniqueOrThrow` requires a unique constraint field in `where` — adding `deletedAt: null` alongside `id` breaks the type because `{ id, deletedAt }` is not a compound unique constraint. Use `findFirstOrThrow` instead.
+
+```ts
+// BAD: returns soft-deleted user
+const user = await prisma.user.findUniqueOrThrow({ where: { id } });
+
+// BAD: Prisma type error — { id, deletedAt } is not a unique constraint
+const user = await prisma.user.findUniqueOrThrow({ where: { id, deletedAt: null } });
+
+// GOOD: findFirstOrThrow supports arbitrary where conditions
+const user = await prisma.user.findFirstOrThrow({ where: { id, deletedAt: null } });
+```
+
+### `deleteMany` without `where` deletes every row
+
+```ts
+// BAD: silently wipes the table
+await prisma.post.deleteMany();
+
+// GOOD
+await prisma.post.deleteMany({ where: { authorId: userId } });
+```
+
+## Best Practices
+
+| Rule | Reason |
+|---|---|
+| `migrate deploy` in CI/CD, `migrate dev` only locally | `migrate dev` can reset the DB on drift |
+| Map entities to response DTOs | Prevents leaking internal fields |
+| Catch `PrismaClientKnownRequestError` at service boundary | Translate to domain errors |
+| Prefer `*OrThrow` methods over manual null checks | Throws P2025 automatically; use `findFirstOrThrow` when filtering non-unique fields |
+| `connection_limit=1` + external pooler in serverless | Prevents connection exhaustion |
+| Always provide `where` on `deleteMany` | Prevents accidental table wipe |
+| Set `updatedAt: new Date()` manually in `updateMany` | `@updatedAt` skips bulk writes |
+
+## Related Skills
+
+- `nestjs-patterns` — NestJS service layer that integrates Prisma
+- `postgres-patterns` — PostgreSQL-level indexing and connection tuning
+- `database-migrations` — multi-step migration planning for production
+- `backend-patterns` — general API and service layer design
diff --git a/tests/hooks/config-protection.test.js b/tests/hooks/config-protection.test.js
index 8f01b4b70..ec57c1375 100644
--- a/tests/hooks/config-protection.test.js
+++ b/tests/hooks/config-protection.test.js
@@ -4,6 +4,7 @@
const assert = require('assert');
const fs = require('fs');
+const os = require('os');
const path = require('path');
const { spawnSync } = require('child_process');
@@ -70,85 +71,249 @@ function runTests() {
let passed = 0;
let failed = 0;
- if (test('blocks protected config file edits through run-with-flags', () => {
- const input = {
- tool_name: 'Write',
- tool_input: {
- file_path: '.eslintrc.js',
- content: 'module.exports = {};'
- }
- };
-
- const result = runHook(input);
- assert.strictEqual(result.code, 2, 'Expected protected config edit to be blocked');
- assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
- assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
- })) passed++; else failed++;
-
- if (test('passes through safe file edits unchanged', () => {
- const input = {
- tool_name: 'Write',
- tool_input: {
- file_path: 'src/index.js',
- content: 'console.log("ok");'
- }
- };
-
- const rawInput = JSON.stringify(input);
- const result = runHook(input);
- assert.strictEqual(result.code, 0, 'Expected safe file edit to pass');
- assert.strictEqual(result.stdout, rawInput, 'Expected exact raw JSON passthrough');
- assert.strictEqual(result.stderr, '', 'Expected no stderr for safe edits');
- })) passed++; else failed++;
-
- if (test('blocks truncated protected config payloads instead of failing open', () => {
- const rawInput = JSON.stringify({
- tool_name: 'Write',
- tool_input: {
- file_path: '.eslintrc.js',
- content: 'x'.repeat(1024 * 1024 + 2048)
+ if (
+ test('blocks protected config file edits through run-with-flags', () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+ try {
+ const absPath = path.join(tmpDir, '.eslintrc.js');
+ fs.writeFileSync(absPath, 'module.exports = {};');
+
+ const input = {
+ tool_name: 'Write',
+ tool_input: {
+ file_path: absPath,
+ content: 'module.exports = {};'
+ }
+ };
+
+ const result = runHook(input);
+ assert.strictEqual(result.code, 2, 'Expected protected config edit to be blocked');
+ assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+ assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
+ } finally {
+ try {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
}
- });
-
- const result = runHook(rawInput);
- assert.strictEqual(result.code, 2, 'Expected truncated protected payload to be blocked');
- assert.strictEqual(result.stdout, '', 'Blocked truncated payload should not echo raw input');
- assert.ok(result.stderr.includes('Hook input exceeded 1048576 bytes'), `Expected size warning, got: ${result.stderr}`);
- assert.ok(result.stderr.includes('truncated payload'), `Expected truncated payload warning, got: ${result.stderr}`);
- })) passed++; else failed++;
-
- if (test('legacy hooks do not echo raw input when they fail without stdout', () => {
- const pluginRoot = path.join(__dirname, '..', `tmp-runner-plugin-${Date.now()}`);
- const scriptDir = path.join(pluginRoot, 'scripts', 'hooks');
- const scriptPath = path.join(scriptDir, 'legacy-block.js');
-
- try {
- fs.mkdirSync(scriptDir, { recursive: true });
- fs.writeFileSync(
- scriptPath,
- '#!/usr/bin/env node\nprocess.stderr.write("blocked by legacy hook\\n");\nprocess.exit(2);\n'
- );
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('passes through safe file edits unchanged', () => {
+ const input = {
+ tool_name: 'Write',
+ tool_input: {
+ file_path: 'src/index.js',
+ content: 'console.log("ok");'
+ }
+ };
+ const rawInput = JSON.stringify(input);
+ const result = runHook(input);
+ assert.strictEqual(result.code, 0, 'Expected safe file edit to pass');
+ assert.strictEqual(result.stdout, rawInput, 'Expected exact raw JSON passthrough');
+ assert.strictEqual(result.stderr, '', 'Expected no stderr for safe edits');
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('blocks truncated protected config payloads instead of failing open', () => {
const rawInput = JSON.stringify({
tool_name: 'Write',
tool_input: {
file_path: '.eslintrc.js',
- content: 'module.exports = {};'
+ content: 'x'.repeat(1024 * 1024 + 2048)
}
});
- const result = runCustomHook(pluginRoot, 'pre:legacy-block', 'scripts/hooks/legacy-block.js', rawInput);
- assert.strictEqual(result.code, 2, 'Expected failing legacy hook exit code to propagate');
- assert.strictEqual(result.stdout, '', 'Expected failing legacy hook to avoid raw passthrough');
- assert.ok(result.stderr.includes('blocked by legacy hook'), `Expected legacy hook stderr, got: ${result.stderr}`);
- } finally {
+ const result = runHook(rawInput);
+ assert.strictEqual(result.code, 2, 'Expected truncated protected payload to be blocked');
+ assert.strictEqual(result.stdout, '', 'Blocked truncated payload should not echo raw input');
+ assert.ok(result.stderr.includes('Hook input exceeded 1048576 bytes'), `Expected size warning, got: ${result.stderr}`);
+ assert.ok(result.stderr.includes('truncated payload'), `Expected truncated payload warning, got: ${result.stderr}`);
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('allows first-time creation of a protected config file', () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+ try {
+ const absPath = path.join(tmpDir, 'eslint.config.mjs');
+ const input = {
+ tool_name: 'Write',
+ tool_input: {
+ file_path: absPath,
+ content: 'export default [];'
+ }
+ };
+
+ const rawInput = JSON.stringify(input);
+ const result = runHook(input);
+ assert.strictEqual(result.code, 0, `Expected exit 0 for first-time creation, got ${result.code}; stderr: ${result.stderr}`);
+ assert.strictEqual(result.stdout, rawInput, 'Expected raw passthrough when creation is allowed');
+ assert.strictEqual(result.stderr, '', `Expected no stderr for first-time creation, got: ${result.stderr}`);
+ } finally {
+ try {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
+ }
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('allows first-time creation when the parent directory does not exist yet', () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
try {
- fs.rmSync(pluginRoot, { recursive: true, force: true });
- } catch {
- // best-effort cleanup
+ // Path under a non-existent subdirectory — statSync returns ENOENT
+ // on the final segment, which should be treated as "does not exist"
+ // and allow the write. (Agent or CLI is expected to create parents
+ // during the Write itself; this hook does not need to.)
+ const absPath = path.join(tmpDir, 'no-such-parent', '.prettierrc');
+ const input = {
+ tool_name: 'Write',
+ tool_input: {
+ file_path: absPath,
+ content: '{}'
+ }
+ };
+
+ const rawInput = JSON.stringify(input);
+ const result = runHook(input);
+ assert.strictEqual(result.code, 0, `Expected exit 0 for ENOENT path, got ${result.code}; stderr: ${result.stderr}`);
+ assert.strictEqual(result.stdout, rawInput, 'Expected raw passthrough when path does not exist');
+ } finally {
+ try {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
+ }
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('blocks protected paths that exist as a dangling symlink', () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+ try {
+ const missingTarget = path.join(tmpDir, 'nowhere.js');
+ const linkPath = path.join(tmpDir, '.eslintrc.js');
+ try {
+ fs.symlinkSync(missingTarget, linkPath);
+ } catch (err) {
+ // Windows without Developer Mode or certain sandboxes disallow
+ // symlinks. Skip cleanly rather than fail the suite.
+ if (err.code === 'EPERM' || err.code === 'EACCES') {
+ console.log(' (skipped: symlink creation not permitted here)');
+ return;
+ }
+ throw err;
+ }
+
+ const input = {
+ tool_name: 'Write',
+ tool_input: {
+ file_path: linkPath,
+ content: 'module.exports = {};'
+ }
+ };
+
+ const result = runHook(input);
+ assert.strictEqual(result.code, 2, `Expected exit 2 for dangling symlink, got ${result.code}; stderr: ${result.stderr}`);
+ assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+ assert.ok(
+ result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'),
+ `Expected block message, got: ${result.stderr}`
+ );
+ } finally {
+ try {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
+ }
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('still blocks writes to an existing protected config file', () => {
+ const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-config-protect-'));
+ try {
+ const absPath = path.join(tmpDir, '.eslintrc.js');
+ fs.writeFileSync(absPath, 'module.exports = { rules: {} };');
+
+ const input = {
+ tool_name: 'Edit',
+ tool_input: {
+ file_path: absPath,
+ content: 'module.exports = { rules: { "no-console": "off" } };'
+ }
+ };
+
+ const result = runHook(input);
+ assert.strictEqual(result.code, 2, 'Expected exit 2 when modifying an existing protected config');
+ assert.strictEqual(result.stdout, '', 'Blocked hook should not echo raw input');
+ assert.ok(result.stderr.includes('BLOCKED: Modifying .eslintrc.js is not allowed.'), `Expected block message, got: ${result.stderr}`);
+ } finally {
+ try {
+ fs.rmSync(tmpDir, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
+ }
+ })
+ )
+ passed++;
+ else failed++;
+
+ if (
+ test('legacy hooks do not echo raw input when they fail without stdout', () => {
+ const pluginRoot = path.join(__dirname, '..', `tmp-runner-plugin-${Date.now()}`);
+ const scriptDir = path.join(pluginRoot, 'scripts', 'hooks');
+ const scriptPath = path.join(scriptDir, 'legacy-block.js');
+
+ try {
+ fs.mkdirSync(scriptDir, { recursive: true });
+ fs.writeFileSync(scriptPath, '#!/usr/bin/env node\nprocess.stderr.write("blocked by legacy hook\\n");\nprocess.exit(2);\n');
+
+ const rawInput = JSON.stringify({
+ tool_name: 'Write',
+ tool_input: {
+ file_path: '.eslintrc.js',
+ content: 'module.exports = {};'
+ }
+ });
+
+ const result = runCustomHook(pluginRoot, 'pre:legacy-block', 'scripts/hooks/legacy-block.js', rawInput);
+ assert.strictEqual(result.code, 2, 'Expected failing legacy hook exit code to propagate');
+ assert.strictEqual(result.stdout, '', 'Expected failing legacy hook to avoid raw passthrough');
+ assert.ok(result.stderr.includes('blocked by legacy hook'), `Expected legacy hook stderr, got: ${result.stderr}`);
+ } finally {
+ try {
+ fs.rmSync(pluginRoot, { recursive: true, force: true });
+ } catch {
+ // best-effort cleanup
+ }
}
- }
- })) passed++; else failed++;
+ })
+ )
+ passed++;
+ else failed++;
console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
process.exit(failed > 0 ? 1 : 0);
diff --git a/tests/hooks/cost-tracker.test.js b/tests/hooks/cost-tracker.test.js
index 4a1f6fef5..9e578b19b 100644
--- a/tests/hooks/cost-tracker.test.js
+++ b/tests/hooks/cost-tracker.test.js
@@ -35,6 +35,14 @@ function withTempHome(homeDir) {
};
}
+function writeTranscript(filePath, entries) {
+ fs.writeFileSync(
+ filePath,
+ entries.map(entry => JSON.stringify(entry)).join('\n') + '\n',
+ 'utf8'
+ );
+}
+
function runScript(input, envOverrides = {}) {
const inputStr = typeof input === 'string' ? input : JSON.stringify(input);
const result = spawnSync('node', [script], {
@@ -64,12 +72,40 @@ function runTests() {
assert.strictEqual(result.stdout, inputStr, 'Expected stdout to match original input');
}) ? passed++ : failed++);
- // 2. Creates metrics file when given valid usage data
- (test('creates metrics file when given valid usage data', () => {
+ // 2. Creates metrics file when given transcript usage data
+ (test('creates metrics file when given transcript usage data', () => {
const tmpHome = makeTempDir();
+ const transcriptPath = path.join(tmpHome, 'session.jsonl');
+ writeTranscript(transcriptPath, [
+ { type: 'user', message: { content: 'ignored' } },
+ {
+ type: 'assistant',
+ message: {
+ model: 'claude-sonnet-4-20250514',
+ usage: {
+ input_tokens: 1000,
+ output_tokens: 500,
+ cache_creation_input_tokens: 200,
+ cache_read_input_tokens: 300,
+ },
+ },
+ },
+ { notJsonShape: true },
+ {
+ type: 'assistant',
+ message: {
+ model: 'claude-opus-4-20250514',
+ usage: {
+ input_tokens: 25,
+ output_tokens: 5,
+ },
+ },
+ },
+ ]);
+
const input = {
- model: 'claude-sonnet-4-20250514',
- usage: { input_tokens: 1000, output_tokens: 500 },
+ session_id: 'session-from-hook',
+ transcript_path: transcriptPath,
};
const result = runScript(input, withTempHome(tmpHome));
assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
@@ -79,8 +115,13 @@ function runTests() {
const content = fs.readFileSync(metricsFile, 'utf8').trim();
const row = JSON.parse(content);
- assert.strictEqual(row.input_tokens, 1000, 'Expected input_tokens to be 1000');
- assert.strictEqual(row.output_tokens, 500, 'Expected output_tokens to be 500');
+ assert.strictEqual(row.session_id, 'session-from-hook', 'Expected input session ID to be recorded');
+ assert.strictEqual(row.transcript_path, transcriptPath, 'Expected transcript_path to be recorded');
+ assert.strictEqual(row.model, 'claude-opus-4-20250514', 'Expected last assistant model to be recorded');
+ assert.strictEqual(row.input_tokens, 1025, 'Expected input_tokens to be summed from transcript');
+ assert.strictEqual(row.output_tokens, 505, 'Expected output_tokens to be summed from transcript');
+ assert.strictEqual(row.cache_write_tokens, 200, 'Expected cache write tokens to be summed from transcript');
+ assert.strictEqual(row.cache_read_tokens, 300, 'Expected cache read tokens to be summed from transcript');
assert.ok(row.timestamp, 'Expected timestamp to be present');
assert.ok(typeof row.estimated_cost_usd === 'number', 'Expected estimated_cost_usd to be a number');
assert.ok(row.estimated_cost_usd > 0, 'Expected estimated_cost_usd to be positive');
diff --git a/tests/hooks/pre-bash-dev-server-block.test.js b/tests/hooks/pre-bash-dev-server-block.test.js
index 7ec978dd2..4f075ddb9 100644
--- a/tests/hooks/pre-bash-dev-server-block.test.js
+++ b/tests/hooks/pre-bash-dev-server-block.test.js
@@ -89,6 +89,110 @@ function runTests() {
assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
}) ? passed++ : failed++);
+ // --- Subshell bypass regression (issue: dev server slipped past via $(), ``, ()) ---
+
+ if (!isWindows) {
+ (test('blocks $(npm run dev) — command substitution', () => {
+ const result = runScript('$(npm run dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ assert.ok(result.stderr.includes('BLOCKED'), 'expected BLOCKED in stderr');
+ }) ? passed++ : failed++);
+
+ (test('blocks `npm run dev` — backtick substitution', () => {
+ const result = runScript('`npm run dev`');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks echo $(npm run dev) — substitution nested in argument', () => {
+ const result = runScript('echo $(npm run dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks (npm run dev) — plain subshell group', () => {
+ const result = runScript('(npm run dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks $(echo a; npm run dev) — substitution with sequenced segments', () => {
+ const result = runScript('$(echo a; npm run dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks (pnpm dev) — plain subshell group with pnpm', () => {
+ const result = runScript('(pnpm dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('allows tmux launcher inside subshell wrapping (exit code 0)', () => {
+ const result = runScript('(tmux new-session -d -s dev "npm run dev")');
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('allows single-quoted "(npm run dev)" — literal string, not a subshell', () => {
+ const result = runScript("git commit -m '(npm run dev)'");
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('allows double-quoted "(npm run dev)" — literal in double quotes (bash does not subshell)', () => {
+ const result = runScript('echo "(npm run dev)"');
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test("allows single-quoted '$(npm run dev)' — literal string, no substitution", () => {
+ const result = runScript("git commit -m '$(npm run dev) fix'");
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+ }
+
+ // --- Round 1 review fixes (Greptile + CodeRabbit on PR #1889) ---
+
+ if (!isWindows) {
+ (test('blocks $(echo ")"; (npm run dev)) — quoted ) does not terminate $() early', () => {
+ const result = runScript('$(echo ")"; (npm run dev))');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks (echo ")"; npm run dev) — quoted ) does not terminate (...) early', () => {
+ const result = runScript('(echo ")"; npm run dev)');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('allows $(echo "(npm run dev)") — () inside double-quoted substitution body is literal', () => {
+ const result = runScript('$(echo "(npm run dev)")');
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks { npm run dev; } — brace group runs in current shell', () => {
+ const result = runScript('{ npm run dev; }');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks echo hi && { npm run dev; } — brace group after &&', () => {
+ const result = runScript('echo hi && { npm run dev; }');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('allows {npm run dev} — bash requires space after { to form a group', () => {
+ const result = runScript('{npm run dev}');
+ assert.strictEqual(result.code, 0, `Expected exit code 0, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks yarn run dev — yarn 1.x convention', () => {
+ const result = runScript('yarn run dev');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks bun dev — bun bare form', () => {
+ const result = runScript('bun dev');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+
+ (test('blocks "$(npm run dev)" — double-quoted substitution still substitutes', () => {
+ const result = runScript('echo "$(npm run dev)"');
+ assert.strictEqual(result.code, 2, `Expected exit code 2, got ${result.code}`);
+ }) ? passed++ : failed++);
+ }
+
// --- Edge cases ---
(test('empty/invalid input passes through (exit code 0)', () => {
diff --git a/tests/hooks/suggest-compact.test.js b/tests/hooks/suggest-compact.test.js
index 217304b4b..dc3c5c232 100644
--- a/tests/hooks/suggest-compact.test.js
+++ b/tests/hooks/suggest-compact.test.js
@@ -366,6 +366,66 @@ function runTests() {
})) passed++;
else failed++;
+ // ── hookSpecificOutput JSON on stdout ──
+ // Claude Code 2.1+ drops non-blocking PreToolUse stderr; the suggestion has
+ // to ride on stdout as { hookSpecificOutput: { additionalContext } } to reach
+ // the model. These tests pin that contract.
+ console.log('\nhookSpecificOutput stdout JSON:');
+
+ if (test('emits hookSpecificOutput.additionalContext on stdout at threshold', () => {
+ const { sessionId, counterFile, cleanup } = createCounterContext();
+ cleanup();
+ fs.writeFileSync(counterFile, '49');
+ const result = runCompact({ CLAUDE_SESSION_ID: sessionId });
+ assert.strictEqual(result.code, 0, 'Should exit 0');
+ assert.ok(result.stdout.trim().length > 0, `Expected stdout payload at threshold. Got: "${result.stdout}"`);
+ const parsed = JSON.parse(result.stdout);
+ assert.strictEqual(parsed.hookSpecificOutput.hookEventName, 'PreToolUse',
+ `hookEventName should be PreToolUse. Got: ${JSON.stringify(parsed)}`);
+ assert.ok(parsed.hookSpecificOutput.additionalContext.includes('50 tool calls reached'),
+ `additionalContext should include threshold text. Got: ${parsed.hookSpecificOutput.additionalContext}`);
+ cleanup();
+ })) passed++;
+ else failed++;
+
+ if (test('emits hookSpecificOutput.additionalContext on stdout at +25 interval', () => {
+ const { sessionId, counterFile, cleanup } = createCounterContext();
+ cleanup();
+ // threshold=3, set counter to 27 → next run = 28 → 28-3=25 → interval hit
+ fs.writeFileSync(counterFile, '27');
+ const result = runCompact({ CLAUDE_SESSION_ID: sessionId, COMPACT_THRESHOLD: '3' });
+ assert.strictEqual(result.code, 0, 'Should exit 0');
+ assert.ok(result.stdout.trim().length > 0, `Expected stdout payload at interval. Got: "${result.stdout}"`);
+ const parsed = JSON.parse(result.stdout);
+ assert.strictEqual(parsed.hookSpecificOutput.hookEventName, 'PreToolUse');
+ assert.ok(parsed.hookSpecificOutput.additionalContext.includes('28 tool calls'),
+ `additionalContext should include count. Got: ${parsed.hookSpecificOutput.additionalContext}`);
+ cleanup();
+ })) passed++;
+ else failed++;
+
+ if (test('emits no stdout below threshold (silent)', () => {
+ const { sessionId, cleanup } = createCounterContext();
+ cleanup();
+ const result = runCompact({ CLAUDE_SESSION_ID: sessionId, COMPACT_THRESHOLD: '5' });
+ assert.strictEqual(result.code, 0);
+ assert.strictEqual(result.stdout.trim(), '',
+ `Expected empty stdout below threshold. Got: "${result.stdout}"`);
+ cleanup();
+ })) passed++;
+ else failed++;
+
+ if (test('still writes [StrategicCompact] to stderr (debug log retained)', () => {
+ const { sessionId, counterFile, cleanup } = createCounterContext();
+ cleanup();
+ fs.writeFileSync(counterFile, '49');
+ const result = runCompact({ CLAUDE_SESSION_ID: sessionId });
+ assert.ok(result.stderr.includes('[StrategicCompact]'),
+ `stderr should retain [StrategicCompact] for debug log capture. Got: "${result.stderr}"`);
+ cleanup();
+ })) passed++;
+ else failed++;
+
// ── Round 64: default session ID fallback ──
console.log('\nDefault session ID fallback (Round 64):');