From ae5c9243c921d941324c53651ff2510ac489eb3f Mon Sep 17 00:00:00 2001 From: Necip Sunmaz Date: Mon, 9 Mar 2026 06:20:26 +0300 Subject: [PATCH] feat: add Perl language rules and update documentation Add rules/perl/ with 5 rule files (coding-style, testing, patterns, hooks, security) following the same structure as existing languages. Update README.md, README.zh-CN.md, and rules/README.md to document Perl support including badges, directory trees, install instructions, and rule counts. --- README.md | 24 ++++++++---- README.zh-CN.md | 52 ++++++++++++++++++-------- rules/README.md | 7 +++- rules/perl/coding-style.md | 46 +++++++++++++++++++++++ rules/perl/hooks.md | 22 +++++++++++ rules/perl/patterns.md | 76 ++++++++++++++++++++++++++++++++++++++ rules/perl/security.md | 69 ++++++++++++++++++++++++++++++++++ rules/perl/testing.md | 54 +++++++++++++++++++++++++++ 8 files changed, 325 insertions(+), 25 deletions(-) create mode 100644 rules/perl/coding-style.md create mode 100644 rules/perl/hooks.md create mode 100644 rules/perl/patterns.md create mode 100644 rules/perl/security.md create mode 100644 rules/perl/testing.md diff --git a/README.md b/README.md index 25d6c091..2e5c7d19 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,10 @@ ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white) ![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white) ![Java](https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white) +![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white) ![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white) -> **50K+ stars** | **6K+ forks** | **30 contributors** | **6 languages supported** | **Anthropic Hackathon Winner** +> **50K+ stars** | **6K+ forks** | **30 contributors** | **7 languages supported** | **Anthropic Hackathon Winner** --- @@ -109,7 +110,7 @@ This repo is the raw code only. The guides explain everything. - **Interactive installation wizard** — New `configure-ecc` skill provides guided setup with merge/overwrite detection - **PM2 & multi-agent orchestration** — 6 new commands (`/pm2`, `/multi-plan`, `/multi-execute`, `/multi-backend`, `/multi-frontend`, `/multi-workflow`) for managing complex multi-service workflows -- **Multi-language rules architecture** — Rules restructured from flat files into `common/` + `typescript/` + `python/` + `golang/` directories. Install only the languages you need +- **Multi-language rules architecture** — Rules restructured from flat files into `common/` + `typescript/` + `python/` + `golang/` + `perl/` directories. Install only the languages you need - **Chinese (zh-CN) translations** — Complete translation of all agents, commands, skills, and rules (80+ files) - **GitHub Sponsors support** — Sponsor the project via GitHub Sponsors - **Enhanced CONTRIBUTING.md** — Detailed PR templates for each contribution type @@ -155,9 +156,9 @@ git clone https://github.com/affaan-m/everything-claude-code.git cd everything-claude-code # Recommended: use the installer (handles common + language rules safely) -./install.sh typescript # or python or golang +./install.sh typescript # or python or golang or perl # You can pass multiple languages: -# ./install.sh typescript python golang +# ./install.sh typescript python golang perl # or target cursor: # ./install.sh --target cursor typescript # or target antigravity: @@ -310,6 +311,9 @@ everything-claude-code/ | |-- liquid-glass-design/ # iOS 26 Liquid Glass design system (NEW) | |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels (NEW) | |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency (NEW) +| |-- perl-patterns/ # Modern Perl 5.36+ idioms and best practices (NEW) +| |-- perl-security/ # Perl security patterns, taint mode, safe I/O (NEW) +| |-- perl-testing/ # Perl TDD with Test2::V0, prove, Devel::Cover (NEW) | |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration (NEW) | |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks (NEW) | @@ -361,6 +365,7 @@ everything-claude-code/ | |-- typescript/ # TypeScript/JavaScript specific | |-- python/ # Python specific | |-- golang/ # Go specific +| |-- perl/ # Perl specific (NEW) | |-- hooks/ # Trigger-based automations | |-- README.md # Hook documentation, recipes, and customization guide @@ -563,6 +568,7 @@ This gives you instant access to all commands, agents, skills, and hooks. > 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/perl/* ~/.claude/rules/ > > # Option B: Project-level rules (applies to current project only) > mkdir -p .claude/rules @@ -588,6 +594,7 @@ 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/perl/* ~/.claude/rules/ # Copy commands cp everything-claude-code/commands/*.md ~/.claude/commands/ @@ -670,6 +677,7 @@ rules/ typescript/ # TS/JS specific patterns and tools python/ # Python specific patterns and tools golang/ # Go specific patterns and tools + perl/ # Perl specific patterns and tools ``` See [`rules/README.md`](rules/README.md) for installation and structure details. @@ -824,7 +832,7 @@ Please contribute! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ### Ideas for Contributions -- Language-specific skills (Rust, C#, Swift, Kotlin) — Go, Python, Java already included +- Language-specific skills (Rust, C#, Swift, Kotlin) — Go, Python, Java, Perl already included - Framework-specific configs (Rails, Laravel, FastAPI, NestJS) — Django, Spring Boot already included - DevOps agents (Kubernetes, Terraform, AWS, Docker) - Testing strategies (different frameworks, visual regression) @@ -841,7 +849,7 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm ```bash # Install for your language(s) ./install.sh --target cursor typescript -./install.sh --target cursor python golang swift +./install.sh --target cursor python golang swift perl ``` ### What's Included @@ -850,7 +858,7 @@ ECC provides **full Cursor IDE support** with hooks, rules, agents, skills, comm |-----------|-------|---------| | Hook Events | 15 | sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more | | Hook Scripts | 16 | Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter | -| Rules | 29 | 9 common (alwaysApply) + 20 language-specific (TypeScript, Python, Go, Swift) | +| Rules | 34 | 9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, Perl) | | Agents | Shared | Via AGENTS.md at root (read by Cursor natively) | | Skills | Shared + Bundled | Via AGENTS.md at root and `.cursor/skills/` for translated additions | | Commands | Shared | `.cursor/commands/` if installed | @@ -1096,7 +1104,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e | **Skills** | 65 | Shared | 10 (native format) | 37 | | **Hook Events** | 8 types | 15 types | None yet | 11 types | | **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks | -| **Rules** | 29 (common + lang) | 29 (YAML frontmatter) | Instruction-based | 13 instructions | +| **Rules** | 34 (common + lang) | 34 (YAML frontmatter) | Instruction-based | 13 instructions | | **Custom Tools** | Via hooks | Via hooks | N/A | 6 native tools | | **MCP Servers** | 14 | Shared (mcp.json) | 4 (command-based) | Full | | **Config Format** | settings.json | hooks.json + rules/ | config.toml | opencode.json | diff --git a/README.zh-CN.md b/README.zh-CN.md index ef72d195..45171f64 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -5,6 +5,7 @@ ![Shell](https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white) ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white) ![Go](https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white) +![Perl](https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white) ![Markdown](https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white) --- @@ -81,8 +82,12 @@ # 首先克隆仓库 git clone https://github.com/affaan-m/everything-claude-code.git -# 复制规则（应用于所有项目） -cp -r everything-claude-code/rules/* ~/.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/perl/* ~/.claude/rules/ ``` ### 第三步：开始使用 @@ -175,6 +180,9 @@ everything-claude-code/ | |-- golang-patterns/ # Go 惯用语和最佳实践（新增） | |-- golang-testing/ # Go 测试模式、TDD、基准测试（新增） | |-- cpp-testing/ # C++ 测试模式、GoogleTest、CMake/CTest（新增） +| |-- perl-patterns/ # 现代 Perl 5.36+ 惯用语和最佳实践（新增） +| |-- perl-security/ # Perl 安全模式、污染模式、安全 I/O（新增） +| |-- perl-testing/ # 使用 Test2::V0、prove、Devel::Cover 的 Perl TDD（新增） | |-- commands/ # 用于快速执行的斜杠命令 | |-- tdd.md # /tdd - 测试驱动开发 @@ -197,12 +205,20 @@ everything-claude-code/ | |-- evolve.md # /evolve - 将直觉聚类到技能中（新增） | |-- rules/ # 始终遵循的指南（复制到 ~/.claude/rules/） -| |-- security.md # 强制性安全检查 -| |-- coding-style.md # 不可变性、文件组织 -| |-- testing.md # TDD、80% 覆盖率要求 -| |-- git-workflow.md # 提交格式、PR 流程 -| |-- agents.md # 何时委托给子代理 -| |-- performance.md # 模型选择、上下文管理 +| |-- README.md # 结构概述和安装指南 +| |-- common/ # 与语言无关的原则 +| | |-- coding-style.md # 不可变性、文件组织 +| | |-- git-workflow.md # 提交格式、PR 流程 +| | |-- testing.md # TDD、80% 覆盖率要求 +| | |-- performance.md # 模型选择、上下文管理 +| | |-- patterns.md # 设计模式、骨架项目 +| | |-- hooks.md # 钩子架构、TodoWrite +| | |-- agents.md # 何时委托给子代理 +| | |-- security.md # 强制性安全检查 +| |-- typescript/ # TypeScript/JavaScript 特定 +| |-- python/ # Python 特定 +| |-- golang/ # Go 特定 +| |-- perl/ # Perl 特定（新增） | |-- hooks/ # 基于触发器的自动化 | |-- hooks.json # 所有钩子配置（PreToolUse、PostToolUse、Stop 等） @@ -356,8 +372,12 @@ git clone https://github.com/affaan-m/everything-claude-code.git # 将代理复制到你的 Claude 配置 cp everything-claude-code/agents/*.md ~/.claude/agents/ -# 复制规则 -cp everything-claude-code/rules/*.md ~/.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/perl/* ~/.claude/rules/ # 复制命令 cp everything-claude-code/commands/*.md ~/.claude/commands/ @@ -425,13 +445,15 @@ model: opus ### 规则 -规则是始终遵循的指南。保持模块化： +规则是始终遵循的指南，分为 `common/`（通用）+ 语言特定目录： ``` ~/.claude/rules/ - security.md # 无硬编码秘密 - coding-style.md # 不可变性、文件限制 - testing.md # TDD、覆盖率要求 + common/ # 通用原则（必装） + typescript/ # TS/JS 特定模式和工具 + python/ # Python 特定模式和工具 + golang/ # Go 特定模式和工具 + perl/ # Perl 特定模式和工具 ``` --- @@ -466,7 +488,7 @@ node tests/hooks/hooks.test.js ### 贡献想法 -- 特定语言的技能（Python、Rust 模式）- 现已包含 Go！ +- 特定语言的技能（Rust、C#、Swift、Kotlin）- 现已包含 Go、Python、Java、Perl！ - 特定框架的配置（Django、Rails、Laravel） - DevOps 代理（Kubernetes、Terraform、AWS） - 测试策略（不同框架） diff --git a/rules/README.md b/rules/README.md index 0cb01485..a9c83776 100644 --- a/rules/README.md +++ b/rules/README.md @@ -17,7 +17,8 @@ rules/ ├── typescript/ # TypeScript/JavaScript specific ├── python/ # Python specific ├── golang/ # Go specific -└── swift/ # Swift specific +├── swift/ # Swift specific +└── perl/ # Perl specific ``` - **common/** contains universal principles — no language-specific code examples. @@ -33,6 +34,7 @@ rules/ ./install.sh python ./install.sh golang ./install.sh swift +./install.sh perl # Install multiple languages at once ./install.sh typescript python @@ -55,6 +57,7 @@ cp -r rules/typescript ~/.claude/rules/typescript cp -r rules/python ~/.claude/rules/python cp -r rules/golang ~/.claude/rules/golang cp -r rules/swift ~/.claude/rules/swift +cp -r rules/perl ~/.claude/rules/perl # Attention ! ! ! Configure according to your actual project requirements; the configuration here is for reference only. ``` @@ -88,7 +91,7 @@ To add support for a new language (e.g., `rust/`): When language-specific rules and common rules conflict, **language-specific rules take precedence** (specific overrides general). This follows the standard layered configuration pattern (similar to CSS specificity or `.gitignore` precedence). - `rules/common/` defines universal defaults applicable to all projects. -- `rules/golang/`, `rules/python/`, `rules/typescript/`, etc. override those defaults where language idioms differ. +- `rules/golang/`, `rules/python/`, `rules/perl/`, `rules/typescript/`, etc. override those defaults where language idioms differ. ### Example diff --git a/rules/perl/coding-style.md b/rules/perl/coding-style.md new file mode 100644 index 00000000..6e522c65 --- /dev/null +++ b/rules/perl/coding-style.md @@ -0,0 +1,46 @@ +--- +paths: + - "**/*.pl" + - "**/*.pm" + - "**/*.t" + - "**/*.psgi" + - "**/*.cgi" +--- +# Perl Coding Style + +> This file extends [common/coding-style.md](../common/coding-style.md) with Perl specific content. + +## Standards + +- Always `use v5.36` (enables `strict`, `warnings`, `say`, subroutine signatures) +- Use subroutine signatures — never unpack `@_` manually +- Prefer `say` over `print` with explicit newlines + +## Immutability + +- Use **Moo** with `is => 'ro'` and `Types::Standard` for all attributes +- Never use blessed hashrefs directly — always use Moo/Moose accessors +- **OO override note**: Moo `has` attributes with `builder` or `default` are acceptable for computed read-only values + +## Formatting + +Use **perltidy** with these settings: + +``` +-i=4 # 4-space indent +-l=100 # 100 char line length +-ce # cuddled else +-bar # opening brace always right +``` + +## Linting + +Use **perlcritic** at severity 3 with themes: `core`, `pbp`, `security`. + +```bash +perlcritic --severity 3 --theme 'core || pbp || security' lib/ +``` + +## Reference + +See skill: `perl-patterns` for comprehensive modern Perl idioms and best practices. diff --git a/rules/perl/hooks.md b/rules/perl/hooks.md new file mode 100644 index 00000000..c8dc850b --- /dev/null +++ b/rules/perl/hooks.md @@ -0,0 +1,22 @@ +--- +paths: + - "**/*.pl" + - "**/*.pm" + - "**/*.t" + - "**/*.psgi" + - "**/*.cgi" +--- +# Perl Hooks + +> This file extends [common/hooks.md](../common/hooks.md) with Perl specific content. + +## PostToolUse Hooks + +Configure in `~/.claude/settings.json`: + +- **perltidy**: Auto-format `.pl` and `.pm` files after edit +- **perlcritic**: Run lint check after editing `.pm` files + +## Warnings + +- Warn about `print` in non-script `.pm` files — use `say` or a logging module (e.g., `Log::Any`) diff --git a/rules/perl/patterns.md b/rules/perl/patterns.md new file mode 100644 index 00000000..ad03fa59 --- /dev/null +++ b/rules/perl/patterns.md @@ -0,0 +1,76 @@ +--- +paths: + - "**/*.pl" + - "**/*.pm" + - "**/*.t" + - "**/*.psgi" + - "**/*.cgi" +--- +# Perl Patterns + +> This file extends [common/patterns.md](../common/patterns.md) with Perl specific content. + +## Repository Pattern + +Use **DBI** or **DBIx::Class** behind an interface: + +```perl +package MyApp::Repo::User; +use Moo; + +has dbh => (is => 'ro', required => 1); + +sub find_by_id ($self, $id) { + my $sth = $self->dbh->prepare('SELECT * FROM users WHERE id = ?'); + $sth->execute($id); + return $sth->fetchrow_hashref; +} +``` + +## DTOs / Value Objects + +Use **Moo** classes with **Types::Standard** (equivalent to Python dataclasses): + +```perl +package MyApp::DTO::User; +use Moo; +use Types::Standard qw(Str Int); + +has name => (is => 'ro', isa => Str, required => 1); +has email => (is => 'ro', isa => Str, required => 1); +has age => (is => 'ro', isa => Int); +``` + +## Resource Management + +- Always use **three-arg open** with `autodie` +- Use **Path::Tiny** for file operations + +```perl +use autodie; +use Path::Tiny; + +my $content = path('config.json')->slurp_utf8; +``` + +## Module Interface + +Use `Exporter 'import'` with `@EXPORT_OK` — never `@EXPORT`: + +```perl +use Exporter 'import'; +our @EXPORT_OK = qw(parse_config validate_input); +``` + +## Dependency Management + +Use **cpanfile** + **carton** for reproducible installs: + +```bash +carton install +carton exec prove -lr t/ +``` + +## Reference + +See skill: `perl-patterns` for comprehensive modern Perl patterns and idioms. diff --git a/rules/perl/security.md b/rules/perl/security.md new file mode 100644 index 00000000..3df3cd75 --- /dev/null +++ b/rules/perl/security.md @@ -0,0 +1,69 @@ +--- +paths: + - "**/*.pl" + - "**/*.pm" + - "**/*.t" + - "**/*.psgi" + - "**/*.cgi" +--- +# Perl Security + +> This file extends [common/security.md](../common/security.md) with Perl specific content. + +## Taint Mode + +- Use `-T` flag on all CGI/web-facing scripts +- Sanitize `%ENV` (`$ENV{PATH}`, `$ENV{CDPATH}`, etc.) before any external command + +## Input Validation + +- Use allowlist regex for untainting — never `/(.*)/s` +- Validate all user input with explicit patterns: + +```perl +if ($input =~ /\A([a-zA-Z0-9_-]+)\z/) { + my $clean = $1; +} +``` + +## File I/O + +- **Three-arg open only** — never two-arg open +- Prevent path traversal with `Cwd::realpath`: + +```perl +use Cwd 'realpath'; +my $safe_path = realpath($user_path); +die "Path traversal" unless $safe_path =~ m{\A/allowed/directory/}; +``` + +## Process Execution + +- Use **list-form `system()`** — never single-string form +- Use **IPC::Run3** for capturing output +- Never use backticks with variable interpolation + +```perl +system('grep', '-r', $pattern, $directory); # safe +``` + +## SQL Injection Prevention + +Always use DBI placeholders — never interpolate into SQL: + +```perl +my $sth = $dbh->prepare('SELECT * FROM users WHERE email = ?'); +$sth->execute($email); +``` + +## Security Scanning + +Run **perlcritic** with the security theme at severity 4+: + +```bash +perlcritic --severity 4 --theme security lib/ +``` + +## Reference + +See skill: `perl-security` for comprehensive Perl security patterns, taint mode, and safe I/O. diff --git a/rules/perl/testing.md b/rules/perl/testing.md new file mode 100644 index 00000000..c1755ada --- /dev/null +++ b/rules/perl/testing.md @@ -0,0 +1,54 @@ +--- +paths: + - "**/*.pl" + - "**/*.pm" + - "**/*.t" + - "**/*.psgi" + - "**/*.cgi" +--- +# Perl Testing + +> This file extends [common/testing.md](../common/testing.md) with Perl specific content. + +## Framework + +Use **Test2::V0** for new projects (not Test::More): + +```perl +use Test2::V0; + +is($result, 42, 'answer is correct'); + +done_testing; +``` + +## Runner + +```bash +prove -l t/ # adds lib/ to @INC +prove -lr -j8 t/ # recursive, 8 parallel jobs +``` + +Always use `-l` to ensure `lib/` is on `@INC`. + +## Coverage + +Use **Devel::Cover** — target 80%+: + +```bash +cover -test +``` + +## Mocking + +- **Test::MockModule** — mock methods on existing modules +- **Test::MockObject** — create test doubles from scratch + +## Pitfalls + +- Always end test files with `done_testing` +- Never forget the `-l` flag with `prove` + +## Reference + +See skill: `perl-testing` for detailed Perl TDD patterns with Test2::V0, prove, and Devel::Cover.