alp-code 0.9.0

package/skills/repomix/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: repomix
+description: Đóng gói cả repo thành một file cho AI đọc (XML, Markdown, JSON), có đếm token và quét secret. Kích hoạt khi cần đưa nguyên một codebase lạ vào context, khi đánh giá thư viện bên thứ ba, hoặc khi cần biết token nằm tập trung ở đâu.
+---
+
+# repomix — gói repo thành một file
+
+**Chưa vai nào được cấp skill này** trong `compiled AgentDefinition`. Nó nằm ở `skills/` để principal
+cấp khi cần — thường là khi phải đánh giá một thư viện lạ.
+
+## Khi nào đáng dùng
+
+Chỉ khi **thật sự cần cả repo**: đánh giá thư viện bên thứ ba, hiểu một codebase chưa từng
+đọc, chuẩn bị audit.
+
+Khi **không** nên dùng: tìm một symbol, đọc một luồng, trả lời một câu hỏi cụ thể về code.
+Việc đó giao một lượt truy xuất code — nó trả `path:line`, còn repomix đổ hàng chục nghìn
+token vào context.
+Dùng nhầm chỗ là phá đúng nguyên tắc "boot set ≤ 7 nguồn" của compiled policy invariants.
+
+## Kiểm tra trước
+
+```bash
+repomix --version
+```
+
+Chưa cài thì **báo principal, đừng tự cài** (HOUSE-RULES §1.2). Cài: `npm install -g repomix`
+hoặc `brew install repomix`.
+
+## Dùng cơ bản
+
+```bash
+repomix                                   # gói thư mục hiện tại → repomix-output.xml
+repomix --style markdown                  # đổi định dạng: xml | markdown | json | plain
+repomix --include "src/**/*.ts" -o out.md # lọc + đặt tên file ra
+npx repomix --remote owner/repo           # gói repo từ xa, không cần clone
+```
+
+**Chỉ gói repo nằm trong `workspaces.read` của loadout.** Gói một repo ngoài danh sách là
+đọc thứ mình không được đọc, kể cả khi filesystem không chặn.
+
+| Nhóm | Cờ |
+|---|---|
+| chọn file | `--include "<glob>"` · `-i "<glob>"` (bỏ qua thêm) · `--no-gitignore` |
+| đầu ra | `--style` · `-o <file>` · `--remove-comments` · `--copy` |
+| cấu hình | `-c <file>` · `--init` (tạo `repomix.config.json`) |
+
+Đầy đủ: `repomix --help` hoặc `references/configuration.md`.
+
+## Đếm token — phần đáng giá nhất
+
+```bash
+repomix --token-count-tree        # cây token toàn repo
+repomix --token-count-tree 1000   # chỉ hiện file/thư mục từ 1000 token trở lên
+```
+
+```
+└── src/ (70,925 tokens)
+    ├── cli/ (12,714 tokens)
+    └── core/ (41,600 tokens)
+```
+
+Chạy cây token **trước** khi gói. Nó cho biết nên `--include` những gì, và tránh việc gói
+xong mới phát hiện vượt giới hạn context.
+
+## Bảo mật — đọc trước khi gói bất cứ thứ gì
+
+repomix dùng Secretlint để bắt API key, mật khẩu, private key, AWS secret.
+
+- **Luôn đọc lại output trước khi đưa đi đâu.** Một file gói có thể chứa credential mà
+  `.gitignore` che được nhưng `.repomixignore` thì chưa.
+- Không gói `.env`.
+- **Không tắt `--no-security-check`** trừ khi principal nói thẳng. Tắt quét secret rồi đổ
+  file vào context là cách lộ credential mà không ai nhìn thấy.
+- File `repomix-output.*` sinh ra trong thư mục làm việc — dọn sau khi dùng, đừng để nó
+  lọt vào commit.
+
+## Quy trình
+
+1. Chạy `--token-count-tree`, xem token nằm ở đâu.
+2. Chốt `--include`/`-i` cho vừa ngân sách context.
+3. Gói, giữ quét secret bật.
+4. **Đọc lại output**, xác nhận không có gì nhạy cảm.
+5. Báo số token và cảnh báo nếu có.
+6. Dọn file gói khi xong.
+
+## Tham chiếu
+
+| File | Nội dung |
+|---|---|
+| `references/configuration.md` | file config, mẫu include/exclude, định dạng ra |
+| `references/usage-patterns.md` | quy trình phân tích, chuẩn bị audit, đánh giá thư viện |
+
+Nguồn: https://github.com/yamadashy/repomix

package/skills/repomix/references/configuration.md

@@ -0,0 +1,134 @@
+# Cấu hình repomix
+
+## File cấu hình
+
+Đặt `repomix.config.json` ở gốc project:
+
+```json
+{
+  "output": {
+    "filePath": "repomix-output.xml",
+    "style": "xml",
+    "removeComments": false,
+    "showLineNumbers": true,
+    "copyToClipboard": false
+  },
+  "include": ["**/*"],
+  "ignore": {
+    "useGitignore": true,
+    "useDefaultPatterns": true,
+    "customPatterns": ["**/*.log", "**/tmp/**"]
+  },
+  "security": {
+    "enableSecurityCheck": true
+  }
+}
+```
+
+Tạo file config trong repo người khác là **sửa repo đó** — hỏi principal trước. Dùng một
+lần thì truyền cờ ở dòng lệnh, đừng để lại file.
+
+### Đầu ra
+
+| Khoá | Nghĩa | Mặc định |
+|---|---|---|
+| `filePath` | file kết quả | `repomix-output.xml` |
+| `style` | `xml` · `markdown` · `json` · `plain` | `xml` |
+| `removeComments` | bỏ comment | `false` |
+| `showLineNumbers` | kèm số dòng | `true` |
+| `copyToClipboard` | tự copy | `false` |
+
+Giữ `showLineNumbers: true` khi mục đích là để trích dẫn — không có số dòng thì không dẫn
+được `path:line`, mà đó là dạng bằng chứng repo này yêu cầu.
+
+### Lọc file
+
+| Khoá | Nghĩa |
+|---|---|
+| `include` | glob các file lấy vào (mặc định `["**/*"]`) |
+| `useGitignore` | tôn trọng `.gitignore` (mặc định `true`) |
+| `useDefaultPatterns` | dùng bộ mẫu bỏ qua mặc định (mặc định `true`) |
+| `customPatterns` | mẫu bỏ qua thêm, cú pháp như `.gitignore` |
+
+**Không tắt `useGitignore`.** Nó là lớp bảo vệ đầu tiên chống việc gói nhầm `.env`, secret,
+và dữ liệu cục bộ.
+
+### Bảo mật
+
+`enableSecurityCheck` (mặc định `true`) — quét bằng Secretlint: API key, mật khẩu,
+credential, private key, secret AWS, chuỗi kết nối DB.
+
+**Không tắt.** Xem phần cuối `SKILL.md`.
+
+## Glob
+
+| Ký hiệu | Khớp |
+|---|---|
+| `*` | mọi ký tự trừ `/` |
+| `**` | mọi ký tự kể cả `/` |
+| `?` | một ký tự |
+| `[abc]` | một ký tự trong tập |
+| `{js,ts}` | một trong các phần mở rộng |
+
+### Thứ tự ưu tiên
+
+Cao xuống thấp:
+
+1. Cờ `-i` ở dòng lệnh
+2. File `.repomixignore`
+3. `customPatterns` trong config
+4. `.gitignore` (nếu bật)
+5. Bộ mẫu mặc định (nếu bật)
+
+Cờ dòng lệnh thắng tất cả — tiện, nhưng cũng nghĩa là một cờ `-i` sai chỗ vô hiệu hoá cả
+bộ lọc bạn đã cấu hình kỹ.
+
+### Mẫu theo loại project
+
+```json
+// TypeScript
+{"include": ["**/*.ts", "**/*.tsx"], "ignore": {"customPatterns": ["**/*.test.ts", "dist/"]}}
+
+// React
+{"include": ["src/**/*.{js,jsx,ts,tsx}", "*.md"], "ignore": {"customPatterns": ["build/"]}}
+
+// Monorepo
+{"include": ["packages/*/src/**"], "ignore": {"customPatterns": ["packages/*/dist/"]}}
+```
+
+## Định dạng ra
+
+| Định dạng | Dùng khi |
+|---|---|
+| `xml` (mặc định) | đưa cho LLM đọc — có tag, phân cấp, metadata |
+| `markdown` | người đọc, review, chia sẻ |
+| `json` | xử lý bằng script |
+| `plain` | nối đơn giản, ít overhead nhất |
+
+Với alp-code, mục đích gần như luôn là đưa cho LLM → giữ `xml`.
+
+## Cờ nâng cao
+
+```bash
+repomix --verbose                 # xem nó đang xử lý gì
+repomix -c /đường/dẫn/config.json # config riêng
+repomix --init                    # tạo repomix.config.json
+repomix --no-line-numbers         # output nhỏ hơn, nhưng mất khả năng dẫn path:line
+```
+
+## Giảm kích thước
+
+Đây là phần quan trọng nhất khi dùng trong một phiên agent — output quá lớn là hỏng cả phiên.
+
+```bash
+repomix --token-count-tree                        # LUÔN chạy trước
+repomix -i "node_modules/**,dist/**,*.min.js"     # loại thứ vô ích
+repomix --include "src/**/*.ts"                   # chỉ lấy phần cần
+repomix --remove-comments --no-line-numbers       # ép nhỏ tối đa
+```
+
+Thứ tự đúng: chạy cây token → xem token nằm ở đâu → chốt `--include` → gói. Gói trước rồi
+mới đo là làm ngược.
+
+Xử lý song song nên repo lớn vẫn nhanh (facebook/react: 123s → 4s). **Nhanh không có nghĩa
+là nên gói cả repo** — giới hạn thật là ngân sách context, không phải thời gian chạy.

package/skills/repomix/references/usage-patterns.md

@@ -0,0 +1,106 @@
+# Mẫu sử dụng
+
+## Bốn việc repomix làm tốt
+
+### 1. Đánh giá thư viện bên thứ ba
+
+Việc đáng dùng repomix nhất: hiểu nhanh một thư viện lạ trước khi quyết định có dùng không.
+
+```bash
+npx repomix --remote https://github.com/owner/repo --token-count-tree
+npx repomix --remote https://github.com/owner/repo \
+  --include "README.md,docs/**,src/index.*" --style markdown
+```
+
+Đọc `README`, `docs/`, và entry point là đủ để đánh giá. Không cần cả `src/`.
+
+### 2. Hiểu một module cụ thể
+
+```bash
+repomix --include "src/auth/**" --remove-comments -o auth.md --style markdown
+```
+
+Khoanh đúng module, không gói cả repo.
+
+### 3. Chuẩn bị audit bảo mật
+
+```bash
+repomix --include "src/**/*.{ts,js}" -i "**/*.test.*" --style xml
+```
+
+Giữ quét secret **bật**. Xem lại output trước khi đưa đi đâu.
+
+### 4. Rút bối cảnh cho tài liệu
+
+```bash
+repomix --include "src/api/**,docs/**" --style markdown -o api-context.md
+```
+
+## Khi KHÔNG dùng repomix
+
+| Việc | Dùng gì thay |
+|---|---|
+| tìm một symbol, một hàm | `rg` / `Grep` |
+| biết đổi chỗ này thì vỡ đâu | `gkg` phân tích ảnh hưởng |
+| đọc tài liệu một thư viện | `docs-seeker` |
+| trả lời một câu hỏi cụ thể về code | một lượt truy xuất trả `path:line` |
+
+repomix đổ hàng chục nghìn token vào context. Dùng nó để trả lời một câu hỏi nhỏ là phá
+đúng nguyên tắc "boot set ≤ 7 nguồn" của CHARTER §2.6.
+
+## Xử lý sự cố
+
+### Output quá lớn
+
+```bash
+repomix --token-count-tree                                    # xem token ở đâu
+repomix -i "node_modules/**,dist/**,coverage/**" \
+        --include "src/core/**" --remove-comments --no-line-numbers
+```
+
+Cắt `--include` cho tới khi vừa ngân sách. Đừng gói rồi mới lo cắt sau.
+
+### Thiếu file mong đợi
+
+```bash
+cat .gitignore .repomixignore                    # xem mẫu nào đang chặn
+repomix --no-gitignore --no-default-patterns --verbose
+```
+
+Lệnh thứ hai **chỉ để chẩn đoán**, không phải để gói thật — tắt `.gitignore` là mở đường
+cho `.env` và dữ liệu cục bộ lọt vào.
+
+### Cảnh báo dữ liệu nhạy cảm
+
+Đúng thứ tự: xem lại file → thêm vào `.repomixignore` → bỏ dữ liệu nhạy cảm khỏi code →
+chuyển sang biến môi trường.
+
+```bash
+repomix --no-security-check     # CHỈ khi đã xác nhận là báo nhầm, và principal đã biết
+```
+
+Tắt quét secret rồi đổ file vào context là cách lộ credential mà không ai nhìn thấy.
+
+### Repo từ xa
+
+```bash
+npx repomix --remote https://github.com/owner/repo
+npx repomix --remote https://github.com/owner/repo/commit/abc123   # đúng commit
+```
+
+Repo private: clone về trước rồi chạy cục bộ — và clone là tải mã nguồn lạ, báo principal.
+
+Ghi lại **commit hoặc tag đã gói**. Không có nó thì kết quả không tái lập được, và không
+đối chiếu được khi thư viện ra bản mới.
+
+## Quy trình
+
+**Trước:** khoanh phạm vi → xác định file cần → chạy `--token-count-tree` → nghĩ tới rủi ro
+bảo mật.
+
+**Trong:** bắt đầu hẹp rồi mở dần, không làm ngược → chọn định dạng đúng mục đích → giữ
+quét secret bật.
+
+**Sau:** xác nhận không có gì nhạy cảm → kiểm đã đủ chưa → **dọn file `repomix-output.*`**.
+
+Bước dọn hay bị quên, và file gói sót lại rất dễ lọt vào commit sau đó.

package/skills/repomix/scripts/README.md

@@ -0,0 +1,179 @@
+# Repomix Scripts
+
+Utility scripts for batch processing repositories with Repomix.
+
+## repomix_batch.py
+
+Batch process multiple repositories (local or remote) using the repomix CLI tool.
+
+### Features
+
+- Process multiple repositories in one command
+- Support local and remote repositories
+- Configurable output formats (XML, Markdown, JSON, Plain)
+- Environment variable loading from multiple .env file locations
+- Comprehensive error handling
+- Progress reporting
+
+### Installation
+
+Requires Python 3.10+ and repomix CLI:
+
+```bash
+# Install repomix
+npm install -g repomix
+
+# Install Python dependencies (if needed)
+pip install pytest pytest-cov pytest-mock  # For running tests
+```
+
+### Usage
+
+**Process single repository:**
+```bash
+python repomix_batch.py /path/to/repo
+```
+
+**Process multiple repositories:**
+```bash
+python repomix_batch.py /repo1 /repo2 /repo3
+```
+
+**Process remote repositories:**
+```bash
+python repomix_batch.py owner/repo1 owner/repo2 --remote
+```
+
+**From JSON file:**
+```bash
+python repomix_batch.py -f repos.json
+```
+
+**With options:**
+```bash
+python repomix_batch.py /repo1 /repo2 \
+  --style markdown \
+  --output-dir output \
+  --remove-comments \
+  --include "src/**/*.ts" \
+  --ignore "tests/**" \
+  --verbose
+```
+
+### Configuration File Format
+
+Create `repos.json` with repository configurations:
+
+```json
+[
+  {
+    "path": "/path/to/local/repo",
+    "output": "custom-output.xml"
+  },
+  {
+    "path": "owner/repo",
+    "remote": true
+  },
+  {
+    "path": "https://github.com/owner/repo",
+    "remote": true,
+    "output": "repo-output.md"
+  }
+]
+```
+
+### Environment Variables
+
+Loads .env files in order of precedence:
+1. Process environment (highest priority)
+2. `./repomix/.env` (skill-specific)
+3. `./skills/.env` (skills directory)
+4. `./.claude/.env` (lowest priority)
+
+### Command Line Options
+
+```
+positional arguments:
+  repos                  Repository paths or URLs to process
+
+options:
+  -h, --help            Show help message
+  -f, --file FILE       JSON file containing repository configurations
+  --style {xml,markdown,json,plain}
+                        Output format (default: xml)
+  -o, --output-dir DIR  Output directory (default: repomix-output)
+  --remove-comments     Remove comments from source files
+  --include PATTERN     Include pattern (glob)
+  --ignore PATTERN      Ignore pattern (glob)
+  --no-security-check   Disable security checks
+  -v, --verbose         Verbose output
+  --remote              Treat all repos as remote URLs
+```
+
+### Examples
+
+**Process local repositories:**
+```bash
+python repomix_batch.py /path/to/repo1 /path/to/repo2 --style markdown
+```
+
+**Process remote repositories:**
+```bash
+python repomix_batch.py yamadashy/repomix facebook/react --remote
+```
+
+**Mixed configuration:**
+```bash
+python repomix_batch.py \
+  /local/repo \
+  --remote owner/remote-repo \
+  -f additional-repos.json \
+  --style json \
+  --remove-comments
+```
+
+**TypeScript projects only:**
+```bash
+python repomix_batch.py /repo1 /repo2 \
+  --include "**/*.ts,**/*.tsx" \
+  --ignore "**/*.test.ts,dist/" \
+  --remove-comments \
+  --style markdown
+```
+
+### Testing
+
+Run tests with coverage:
+
+```bash
+cd tests
+pytest test_repomix_batch.py -v --cov=repomix_batch --cov-report=term-missing
+```
+
+Current coverage: 99%
+
+### Exit Codes
+
+- `0` - All repositories processed successfully
+- `1` - One or more repositories failed or error occurred
+
+### Troubleshooting
+
+**repomix not found:**
+```bash
+npm install -g repomix
+```
+
+**Permission denied:**
+```bash
+chmod +x repomix_batch.py
+```
+
+**Timeout errors:**
+- Default timeout: 5 minutes per repository
+- Reduce scope with `--include` patterns
+- Exclude large directories with `--ignore`
+
+**No repositories specified:**
+- Provide repository paths as arguments
+- Or use `-f` flag with JSON config file