@torus-engineering/tas-kit 1.8.0 → 1.10.0

package/.claude/commands/tas-apitest-plan.md

@@ -0,0 +1,173 @@
+# /tas-apitest-plan $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Generate API Test Specification (Markdown) từ API Spec (OpenAPI 3.0, Markdown, YAML) hoặc phân tích code API.
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Đọc toàn bộ spec hoặc phân tích code trước khi tạo test spec |
+| **Always** | Tổ chức test cases theo API version — mỗi version một section riêng |
+| **Always** | Append-only: không sửa sections trong version cũ đã tồn tại |
+| **Always** | Coverage matrix: mỗi endpoint cần ≥1 happy path + ≥1 error path |
+| **Always** | Đọc `.claude/rules/csharp/api-testing.md` để nắm convention |
+| **Ask** | Khi spec không rõ expected response schema hoặc business rule |
+| **Never** | Sử dụng version folder/syntax trong test spec file (dùng section headers thay vì) |
+| **Never** | Bỏ qua error path — mỗi endpoint cần cover validation errors |
+
+## Hành động
+
+### Bước 1 — Locate Inputs
+
+`$ARGUMENTS` là path đến:
+- API Spec file (OpenAPI 3.0 JSON/YAML, Markdown)
+- Hoặc Story ID — glob tìm `docs/epics/**/Story-{ID}*.md`
+- Hoặc path tới project code API cần phân tích
+
+Nếu không có → hỏi user:
+```
+Nhập input cho /tas-apitest-plan:
+1. Path đến API Spec file (OpenAPI/Markdown/YAML)
+2. Story ID (để tìm link spec trong Story)
+3. Path đến code API cần phân tích tự động
+```
+
+### Bước 2 — Detect Existing Test Spec
+
+Glob tìm `docs/tests/API-Test-Spec-*.md`.
+
+- **Tìm thấy**: Đọc file, detect versions đã có (tìm section headers `## v{N}`)
+- **Không tìm thấy**: Tạo mới với version v1
+
+### Bước 3 — Parse Input
+
+**Nếu là API Spec file:**
+- Đọc và parse OpenAPI/Markdown/YAML
+- Thu thập cho mỗi endpoint:
+  - HTTP method + path, path/query params, request body schema
+  - Response schemas theo từng status code
+  - Auth requirement, description/summary
+  - Tags để nhóm endpoints
+
+**Nếu là Story:**
+- Đọc Story để tìm link spec trong `## Technical Plan` hoặc `## Acceptance Criteria`
+- Parse spec như trên
+- Thêm AC mapping vào test spec
+
+**Nếu là code path:**
+- Glob tìm controller/handler files (`.cs`, `.ts`, `.py` tùy stack)
+- Phân tích attributes/routes để phát hiện endpoints
+- Extract DTO classes để biết request/response schema
+- Hỏi user confirm nếu detect không rõ
+
+### Bước 4 — Detect API Version
+
+Ưu tiên theo thứ tự:
+1. `info.version` trong OpenAPI
+2. Prefix trong URL path (v1/, v2/)
+3. Hỏi user
+
+Version format: `v1`, `v2` (không có dot).
+
+### Bước 5 — Determine Output Path
+
+Output: `docs/tests/API-Test-Spec-{slug}.md`
+
+**Slug generation:**
+- Từ `api_name` trong spec → lowercase, replace spaces với dashes
+- Hoặc hỏi user nhập slug ngắn gọn (ví dụ: `users`, `orders`, `products`)
+
+### Bước 6 — Determine Update Mode
+
+Nếu spec file đã tồn tại và version đã có:
+- **Append mode** (default): thêm test cases mới vào cuối section version hiện tại
+- Hỏi user nếu muốn tạo version mới (v2, v3...):
+
+```
+Spec file đã có với version {current}. Bạn muốn:
+1. Append test cases vào version {current} (default)
+2. Tạo version mới (v{next}) cho test cases
+```
+
+### Bước 7 — Generate Test Spec
+
+Đọc template `.tas/templates/API-Test-Spec.md` để nắm cấu trúc.
+
+**Phân tích endpoints để tạo coverage matrix:**
+
+Với mỗi endpoint, generate test cases cho:
+1. **Happy path** (2xx) — luôn có
+2. **Unauthorized** (401) — nếu endpoint yêu cầu auth
+3. **Forbidden** (403) — nếu có RBAC/ownership check
+4. **Not found** (404) — nếu có path param
+5. **Validation error** (400/422) — nếu có required fields hoặc business rules
+6. **Business rules** — từ Story ACs hoặc spec descriptions
+
+**Coverage matrix format:**
+```
+| Endpoint | Happy Path | 401 Unauthorized | 403 Forbidden | 404 Not Found | 400/422 Validation | Business Rule |
+|----------|:---------:|:----------------:|:-------------:|:-------------:|:------------------:|:-------------:|
+| GET /api/users | ✓ | ✓ | | | | |
+| POST /api/users | ✓ | ✓ | | | ✓ | |
+```
+
+**Test case detail format:**
+```
+#### TC-XXX: {Title} — {Modifier}
+- **Endpoint**: `{METHOD} {path}`
+- **Auth**: Required/Not Required
+- **Preconditions**:
+  - {List preconditions}
+- **Request Query/Path/Body**:
+  - {Request details}
+- **Expected Response**:
+  - Status: {code}
+  - Body: {schema}
+- **Assertions**:
+  - {List assertions}
+- **AC Reference**: AC-{N} (nếu có)
+- **Test Method Name**: `{Method}_{Resource}_Returns{Status}_When{Condition}`
+```
+
+### Bước 8 — Write Test Spec File
+
+**File chưa tồn tại:** Tạo mới từ template.
+
+**File đã tồn tại (append mode):**
+- Đọc file hiện tại
+- Find section `## v{N}` mà đang làm việc
+- Append test cases mới vào cuối section trước `## Version History` hoặc `## Changelog`
+- Preserve toàn bộ content cũ
+
+### Bước 9 — Summary
+
+Hiển thị:
+1. Output file path
+2. Number of endpoints detected
+3. Number of test cases generated
+4. Coverage matrix
+5. Next steps:
+   - Review test spec file
+   - Run `/tas-apitest docs/tests/API-Test-Spec-{slug}.md` để generate code
+
+```
+## API Test Spec Generated
+
+**Output**: `docs/tests/API-Test-Spec-{slug}.md`
+**Version**: v{N}
+**Endpoints**: {N}
+**Test Cases**: {N}
+
+### Coverage Matrix
+[Print coverage matrix]
+
+### Next Steps
+1. Review test spec: `docs/tests/API-Test-Spec-{slug}.md`
+2. Generate test code: `/tas-apitest docs/tests/API-Test-Spec-{slug}.md`
+3. Run tests: `dotnet test tests/ApiTests/`
+```
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào test spec file.

package/.claude/commands/tas-apitest.md

@@ -0,0 +1,143 @@
+# /tas-apitest $ARGUMENTS
+
+Vai trò: SE - Software Engineer
+Generate .NET xUnit automation test project cho REST API từ API Test Spec file (Markdown).
+
+## Always / Ask / Never
+
+| | Hành động |
+|---|---|
+| **Always** | Đọc toàn bộ API Test Spec file trước khi generate bất kỳ test nào |
+| **Always** | Tổ chức tests theo API version — mỗi version một folder riêng |
+| **Always** | Append-only: không sửa files trong version folder cũ đã tồn tại |
+| **Always** | URL và credentials ra `appsettings.json` — không hardcode trong code |
+| **Always** | XML doc comment trên mỗi test method |
+| **Ask** | Khi test spec không rõ expected response schema |
+| **Never** | Sửa hoặc xóa test files của version cũ hơn |
+| **Never** | Hardcode base URL, API key, credentials trong test code |
+| **Never** | Bỏ qua error path — mỗi endpoint cần ≥1 happy path + ≥1 error path |
+
+## Hành động
+
+### Bước 1 — Locate Input
+
+`$ARGUMENTS` là path đến API Test Spec file: `docs/tests/API-Test-Spec-{slug}.md`.
+
+Nếu không có → hỏi user:
+```
+Nhập path đến API Test Spec file (vd: docs/tests/API-Test-Spec-users.md)
+```
+
+### Bước 2 — Parse API Test Spec
+
+Đọc `.claude/rules/csharp/api-testing.md` để nắm convention trước khi generate.
+
+Từ API Test Spec file, thu thập:
+- API version
+- Endpoints với method, path, params
+- Test cases theo từng endpoint (TC-XXX)
+- Request/response schemas
+- Auth requirements
+- Test data requirements
+- Setup/teardown notes
+
+### Bước 3 — Detect Existing Test Project
+
+Glob tìm `**/ApiTests/*.csproj`, `**/Api.Tests/*.csproj`, `**/IntegrationTests/*.csproj`.
+
+- **Tìm thấy**: Đọc framework đang dùng (xUnit/NUnit/MSTest), glob `v*/` folders để biết versions đã có.
+- **Không tìm thấy**: Tạo mới tại `tests/ApiTests/` với xUnit + FluentAssertions (per `csharp/testing.md`).
+
+### Bước 4 — Get API Version from Spec
+
+Đọc version từ API Test Spec file (tìm frontmatter `api_version` hoặc section headers `## v{N}`).
+
+Version folder: lowercase, không có dot — `v1`, `v2` (không phải `v1.0`).
+
+### Bước 5 — Generate Infrastructure (chỉ khi tạo project mới)
+
+Đọc `.claude/rules/csharp/api-testing.md` section **Project Structure** và **Config Pattern** để generate:
+- `ApiTests.csproj` với packages chuẩn
+- `appsettings.json` (base) + `appsettings.Test.json` + `appsettings.Staging.json` với values từ spec
+- `Shared/TestBase.cs` — load config, HttpClient, helper methods
+- `Shared/ApiTestSettings.cs` — strongly typed settings
+- `.gitignore` cho `appsettings.*.local.json`
+
+### Bước 6 — Generate Test Classes từ Spec
+
+Nhóm endpoints theo resource. Mỗi nhóm → `tests/ApiTests/{version}/{Resource}ApiTests.cs`.
+
+Với mỗi test case (TC-XXX) trong spec:
+1. Đọc test case details
+2. Map sang test method với naming: `{HttpMethod}_{Resource}_Returns{Status}_When{Condition}`
+3. Generate XML doc từ test case title
+4. Generate assertions từ expected response
+5. Add AC reference comment nếu có
+
+Test class header comment:
+```csharp
+// ============================================================
+// {Resource} API Tests — v{N}
+// Spec: docs/tests/API-Test-Spec-{slug}.md
+// Generated: {YYYY-MM-DD}
+// Story: {ID} (if applicable)
+// APPEND-ONLY: không sửa methods đã tồn tại.
+// ============================================================
+```
+
+### Bước 7 — Append-Only Guard
+
+Trước khi ghi file: kiểm tra file đã tồn tại chưa.
+- **File chưa có** → tạo mới bình thường.
+- **File đã có** trong version folder → check từng test method:
+  - Method đã tồn tại (cùng tên) → **SKIP**, không ghi đè
+  - Method chưa có → append vào cuối class
+
+### Bước 8 — Generate Test Data Files (nếu spec yêu cầu)
+
+Nếu spec có `test-data.{env}.json` references:
+- Tạo `tests/ApiTests/data/test-data.Test.json` với sample data từ spec
+- Hướng dẫn user tạo `test-data.Staging.json` và `test-data.local.json`
+
+### Bước 9 — Post-Generate Review
+
+Launch `csharp-reviewer` agent:
+> Review `tests/ApiTests/{version}/`. Đọc `.claude/rules/csharp/testing.md` + `.claude/rules/csharp/api-testing.md`.
+> Tập trung: async/await, HttpClient disposal, assertion completeness, XML doc coverage.
+> Format: Critical / High / Medium / Low với file:line.
+
+Gate: Critical/High → fix ngay. Medium/Low → list gợi ý.
+
+### Bước 10 — Summary
+
+Hiển thị:
+1. Test project path
+2. Number of test classes generated
+3. Number of test methods generated
+4. Coverage matrix (so với spec)
+5. Next steps để chạy tests
+
+```
+## API Tests Generated
+
+**Project**: `tests/ApiTests/`
+**Version**: v{N}
+**Test Classes**: {N}
+**Test Methods**: {N}
+
+### Generated Files
+- tests/ApiTests/{version}/{Resource}ApiTests.cs
+- tests/ApiTests/Shared/TestBase.cs (if new project)
+
+### Coverage (vs Spec)
+[Print coverage table: spec test cases vs generated methods]
+
+### Next Steps
+1. Configure test environment: edit tests/ApiTests/appsettings.Test.json
+2. Add test data: tests/ApiTests/data/test-data.Test.json
+3. Run tests: `dotnet test tests/ApiTests/`
+```
+
+## Bước cuối — Token Log
+
+Invoke skill `token-logger`: ghi AI Usage Log vào API Test Spec file.

package/.claude/commands/tas-security.md

@@ -8,7 +8,13 @@ Kiểm tra bảo mật codebase, lưu báo cáo vào docs/security-report.md.
 ## Hành động
 
 ### Bước 1 — Xác định scope
-`$ARGUMENTS` có thể là: file path, directory, hoặc để trống (scan toàn bộ codebase).
+`$ARGUMENTS` có thể là:
+- File path hoặc directory → scan scope chỉ định
+- Để trống → scan toàn bộ codebase
+- `--staged` → chỉ scan các file đang staged (giống pre-commit hook), nhanh + dùng để self-test trước khi commit
+
+Với `--staged`: lấy danh sách từ `git diff --cached --name-only --diff-filter=ACM` và chỉ review các file đó. Dùng chung regex patterns với `.tas/hooks/security-scan.js` rồi bổ sung deep review bằng agents bên dưới.
+
 Đọc `.tas/checklists/security.md` để lấy checklist.
 
 ### Bước 2 — Parallel Security Scan