@torus-engineering/tas-kit 1.8.0 → 1.10.0

package/.tas/tas-example.yaml

@@ -1,109 +1,126 @@
-# .tas/tas-example.yaml - Reference template cho tas.yaml ở root
-# Copy file này ra root (tas.yaml) và điền thông tin dự án.
-# File này CHỈ chứa flow và logic của TAS.
-# Tech stack, coding conventions, build commands thuộc về CLAUDE.md.
-
-project:
-  name: "My Project"
-  code: "PROJ"              # Prefix for file naming: PROJ-Epic-001, PROJ-Feature-001, etc.
-  type: greenfield          # greenfield | brownfield
-  description: "Mô tả ngắn về dự án"
-
-# Azure DevOps integration
-ado:
-  enabled: true                 # false nếu project không dùng ADO
-  organization: "https://dev.azure.com/torus-bellesoft"
-  project_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
-
-team:
-  - name: "Nguyen Van A"
-    role: pe
-    ado_id: "nguyenvana@torus.vn"
-  - name: "Tran Van B"
-    role: se
-    ado_id: "tranvanb@torus.vn"
-  - name: "Le Van C"
-    role: dse
-    ado_id: "levanc@torus.vn"
-
-# Flow configuration
-workflow:
-  # Phase 0: Discovery & Design (Human-led, AI-powered)
-  discovery:
-    enabled: true
-    lead: pe
-    artifacts:
-      - prd
-      - design_spec
-      - sad
-      - adr
-      - epic
-      - feature
-      - story
-    gate: ready_for_development
-
-  # Phase 1: Develop (Orchestrated Agentic)
-  develop:
-    enabled: true
-    lead: se
-    environment: test
-    use_tdd: true
-    auto_review: true
-
-  # Phase 2: Verify (Agentic + PE Review)
-  verify:
-    enabled: true
-    lead: pe
-    environment: staging
-    auto_integration_test: true
-    gate: pe_approved
-
-  # Phase 3: Deploy with Feature Flag (Agentic)
-  deploy:
-    enabled: true
-    lead: dse
-    environment: production
-    feature_flag: true
-    gate: pe_approved_production
-
-  # Phase 4: Operate (Autonomous)
-  operate:
-    enabled: false
-    lead: dse
-    environment: production
-    security_check: true
-    performance_monitor: true
-
-# Brownfield-specific config
-brownfield:
-  existing_docs_path: "docs/"
-  codebase_scan_on_init: true
-
-# Template overrides (optional)
-templates:
-  sad: ".tas/templates/SAD.md"
-  adr: ".tas/templates/ADR.md"
-  prd: ".tas/templates/PRD.md"
-  epic: ".tas/templates/Epic.md"
-  feature: ".tas/templates/Feature.md"
-  story: ".tas/templates/Story.md"
-  bug: ".tas/templates/Bug.md"
-
-# Model mapping
-models:
-  default: sonnet
-  commands:
-    tas-prd: sonnet
-    tas-design: sonnet
-    tas-sad: opus
-    tas-adr: opus
-    tas-epic: sonnet
-    tas-feature: sonnet
-    tas-story: sonnet
-    tas-dev: sonnet
-    tas-review-code: opus
-    tas-brainstorm: opus
-    tas-bug: sonnet
-    tas-verify: haiku
-    tas-status: haiku
-    tas-security-check: opus
+# .tas/tas-example.yaml - Reference template cho tas.yaml ở root
+# Copy file này ra root (tas.yaml) và điền thông tin dự án.
+# File này CHỈ chứa flow và logic của TAS.
+# Tech stack, coding conventions, build commands thuộc về CLAUDE.md.
+
+project:
+  name: "My Project"
+  code: "PROJ"              # Prefix for file naming: PROJ-Epic-001, PROJ-Feature-001, etc.
+  type: greenfield          # greenfield | brownfield
+  description: "Mô tả ngắn về dự án"
+
+# Azure DevOps integration
+ado:
+  enabled: true                 # false nếu project không dùng ADO
+  organization: "https://dev.azure.com/torus-bellesoft"
+  project_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+
+team:
+  - name: "Nguyen Van A"
+    role: pe
+    ado_id: "nguyenvana@torus.vn"
+  - name: "Tran Van B"
+    role: se
+    ado_id: "tranvanb@torus.vn"
+  - name: "Le Van C"
+    role: dse
+    ado_id: "levanc@torus.vn"
+
+# Flow configuration
+workflow:
+  # Phase 0: Discovery & Design (Human-led, AI-powered)
+  discovery:
+    enabled: true
+    lead: pe
+    artifacts:
+      - prd
+      - design_spec
+      - sad
+      - adr
+      - epic
+      - feature
+      - story
+    gate: ready_for_development
+
+  # Phase 1: Develop (Orchestrated Agentic)
+  develop:
+    enabled: true
+    lead: se
+    environment: test
+    use_tdd: true
+    auto_review: true
+
+  # Phase 2: Verify (Agentic + PE Review)
+  verify:
+    enabled: true
+    lead: pe
+    environment: staging
+    auto_integration_test: true
+    gate: pe_approved
+
+  # Phase 3: Deploy with Feature Flag (Agentic)
+  deploy:
+    enabled: true
+    lead: dse
+    environment: production
+    feature_flag: true
+    gate: pe_approved_production
+
+  # Phase 4: Operate (Autonomous)
+  operate:
+    enabled: false
+    lead: dse
+    environment: production
+    security_check: true
+    performance_monitor: true
+
+# Brownfield-specific config
+brownfield:
+  existing_docs_path: "docs/"
+  codebase_scan_on_init: true
+
+# Pre-commit security hook (installed via tas-kit install --security-hook=husky|native)
+# See .tas/hooks/README.md for details
+#
+# 3-tier scan:
+#   Tier 1 (always): built-in regex scan for ~45 secret patterns — blocks
+#   Tier 2 (if on PATH): gitleaks / trufflehog — only runs if installed — blocks
+#   Tier 3 (opt-in, LOCAL ONLY): AI deep scan → writes docs/security-report.md;
+#                                does NOT block. Use a personal Claude Code
+#                                subscription (no API charges). Not for CI.
+security:
+  pre_commit_hook: true                    # master switch; false to disable without uninstalling
+  external_scanner: auto                   # auto | gitleaks | trufflehog | none — tier 2
+  tool: claude                             # claude | codex | gemini | none — tier 3 AI (report-only)
+  deep_scan_on_every_commit: false         # true = opt into tier 3 AI review each local commit
+  block_on: [critical, high]               # severities that block commit (tier 1 & 2 only)
+  allow_bypass: true                       # print hint about SKIP_SECURITY_SCAN / --no-verify
+
+# Template overrides (optional)
+templates:
+  sad: ".tas/templates/SAD.md"
+  adr: ".tas/templates/ADR.md"
+  prd: ".tas/templates/PRD.md"
+  epic: ".tas/templates/Epic.md"
+  feature: ".tas/templates/Feature.md"
+  story: ".tas/templates/Story.md"
+  bug: ".tas/templates/Bug.md"
+
+# Model mapping
+models:
+  default: sonnet
+  commands:
+    tas-prd: sonnet
+    tas-design: sonnet
+    tas-sad: opus
+    tas-adr: opus
+    tas-epic: sonnet
+    tas-feature: sonnet
+    tas-story: sonnet
+    tas-dev: sonnet
+    tas-review-code: opus
+    tas-brainstorm: opus
+    tas-bug: sonnet
+    tas-verify: haiku
+    tas-status: haiku
+    tas-security-check: opus

package/.tas/templates/API-Test-Spec.md

@@ -0,0 +1,400 @@
+---
+api_name:
+api_slug:
+api_version:
+spec_source:
+code_path:
+status:
+created_date:
+updated_date:
+executor:
+story_id:
+framework: xUnit
+---
+
+# API Test Specification: {API Name}
+
+**API Version**: v{api_version}
+**Framework**: {framework}
+**Author**: @[executor]
+**Created**: [created_date]
+**Updated**: [updated_date]
+**Status**: [status] (Draft | Review | Approved | Deprecated)
+**Spec Source**: [spec_source]
+**Code Path**: [code_path]
+**Story**: [story_id] (if applicable)
+
+---
+
+## Version History
+
+> Mỗi API version có section riêng biệt. APPEND-ONLY: không sửa version cũ.
+
+| Version | Status | Created | Description |
+|---------|--------|---------|-------------|
+| v1 | Draft | [created_date] | Initial version |
+| v2 | Draft | [updated_date] | Added new endpoints |
+
+---
+
+## Test Environment Setup
+
+### Configuration (appsettings.json)
+
+```json
+{
+  "ApiTest": {
+    "BaseUrl": "https://localhost:5001",
+    "TimeoutSeconds": 30,
+    "Auth": {
+      "Type": "Bearer",
+      "TokenEndpoint": "/api/auth/token",
+      "Username": "",
+      "Password": ""
+    }
+  }
+}
+```
+
+### Environment-Specific Overrides
+
+| Environment | BaseUrl | Notes |
+|-------------|---------|-------|
+| Local | https://localhost:5001 | Development environment |
+| Test | https://test-api.example.com | Shared test environment |
+| Staging | https://staging-api.example.com | Pre-production |
+| Production | https://api.example.com | Smoke tests only |
+
+### Test Data Requirements
+
+| Data Item | Value | Source | Environment-Specific | Notes |
+|-----------|-------|--------|---------------------|-------|
+| Test User Email | test@example.com | test-data.{env}.json | Yes | Different per env |
+| Test User Password | (from .env) | process.env.APITEST__AUTH__PASSWORD | Yes | NEVER hardcode |
+| Auth Token | Generated at runtime | POST /api/auth/token | Yes | Refresh per test class |
+| {Entity} ID | {value} | test-data.{env}.json | Yes | Pre-seeded data |
+
+### Setup/Teardown Notes
+
+**Before All Tests:**
+- Authenticate and store token for authenticated requests
+- Seed test data if required
+- Configure HttpClient with base address and timeout
+
+**After All Tests:**
+- Dispose HttpClient
+- Clean up test data (unless debugging needed)
+
+**Before Each Test:**
+- Reset state if needed (clear headers, reset counters)
+
+**After Each Test:**
+- Log test result
+- Capture response on failure for debugging
+
+---
+
+## v{N} — Test Cases
+
+### Endpoints Overview
+
+| Method | Path | Description | Auth Required |
+|--------|------|-------------|---------------|
+| GET | /api/users | List users | Yes |
+| POST | /api/users | Create user | Yes |
+| GET | /api/users/{id} | Get user by ID | Yes |
+| PUT | /api/users/{id} | Update user | Yes |
+| DELETE | /api/users/{id} | Delete user | Yes |
+
+### Coverage Matrix
+
+| Endpoint | Happy Path | 401 Unauthorized | 403 Forbidden | 404 Not Found | 400/422 Validation | Business Rule |
+|----------|:---------:|:----------------:|:-------------:|:-------------:|:------------------:|:-------------:|
+| GET /api/users | ✓ | ✓ | | | | |
+| POST /api/users | ✓ | ✓ | | | ✓ | |
+| GET /api/users/{id} | ✓ | ✓ | | ✓ | | |
+| PUT /api/users/{id} | ✓ | ✓ | | ✓ | ✓ | |
+| DELETE /api/users/{id} | ✓ | ✓ | ✓ | ✓ | | |
+
+---
+
+### Test Case Details
+
+#### GET /api/users — List Users
+
+##### TC-001: Happy Path — Returns Paginated User List
+- **Endpoint**: `GET /api/users?page=1&limit=10`
+- **Auth**: Required (Bearer token)
+- **Preconditions**:
+  - Valid authentication token
+  - At least 10 users exist in database
+- **Request Query Params**:
+  - `page`: 1
+  - `limit`: 10
+- **Expected Response**:
+  - Status: 200 OK
+  - Body:
+    ```json
+    {
+      "data": [
+        {
+          "id": "guid",
+          "email": "user@example.com",
+          "name": "John Doe",
+          "role": "User",
+          "createdAt": "2024-01-01T00:00:00Z"
+        }
+      ],
+      "total": 100,
+      "page": 1,
+      "limit": 10
+    }
+    ```
+- **Assertions**:
+  - Response status is 200
+  - `data` is array with length ≤ 10
+  - Each item has required fields: id, email, name, role, createdAt
+  - `total` ≥ 0
+  - `page` and `limit` match request
+- **AC Reference**: N/A (API spec)
+- **Test Method Name**: `Get_Users_Returns200_WhenAuthenticated`
+
+##### TC-002: Security — Returns 401 When No Token
+- **Endpoint**: `GET /api/users`
+- **Auth**: Not provided
+- **Preconditions**: None
+- **Expected Response**:
+  - Status: 401 Unauthorized
+  - Body contains error message
+- **Assertions**:
+  - Response status is 401
+- **AC Reference**: N/A
+- **Test Method Name**: `Get_Users_Returns401_WhenNotAuthenticated`
+
+##### TC-003: Edge Case — Empty List When No Users Exist
+- **Endpoint**: `GET /api/users`
+- **Auth**: Required
+- **Preconditions**:
+  - Database is empty or no users match filter
+- **Expected Response**:
+  - Status: 200 OK
+  - Body:
+    ```json
+    {
+      "data": [],
+      "total": 0,
+      "page": 1,
+      "limit": 10
+    }
+    ```
+- **Assertions**:
+  - Response status is 200
+  - `data` is empty array
+  - `total` is 0
+- **AC Reference**: N/A
+- **Test Method Name**: `Get_Users_ReturnsEmptyArray_WhenNoUsersExist`
+
+#### POST /api/users — Create User
+
+##### TC-004: Happy Path — Creates New User
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "email": "newuser@example.com",
+    "name": "New User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 201 Created
+  - Body contains created user with generated `id`
+  - `Location` header contains URL of new resource
+- **Assertions**:
+  - Response status is 201
+  - `id` is valid GUID
+  - `email`, `name`, `role` match request
+  - `password` is NOT in response
+  - `createdAt` is recent
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns201_WhenValidRequest`
+
+##### TC-005: Validation — Returns 400 When Email Invalid
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "email": "invalid-email",
+    "name": "Test User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 400 Bad Request
+  - Body contains validation errors
+- **Assertions**:
+  - Response status is 400
+  - Error message indicates email format issue
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns400_WhenEmailInvalid`
+
+##### TC-006: Business Rule — Returns 409 When Email Already Exists
+- **Endpoint**: `POST /api/users`
+- **Auth**: Required
+- **Preconditions**: User with email already exists
+- **Request Body**:
+  ```json
+  {
+    "email": "existing@example.com",
+    "name": "Test User",
+    "password": "SecurePass123!",
+    "role": "User"
+  }
+  ```
+- **Expected Response**:
+  - Status: 409 Conflict
+  - Body indicates email already registered
+- **Assertions**:
+  - Response status is 409
+  - Error message mentions duplicate email
+- **AC Reference**: N/A
+- **Test Method Name**: `Post_Users_Returns409_WhenEmailAlreadyExists`
+
+#### GET /api/users/{id} — Get User by ID
+
+##### TC-007: Happy Path — Returns User When ID Exists
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Path Params**: `id` = valid GUID
+- **Expected Response**:
+  - Status: 200 OK
+  - Body contains user details
+- **Assertions**:
+  - Response status is 200
+  - All required fields present
+- **AC Reference**: N/A
+- **Test Method Name**: `GetById_Users_Returns200_WhenExists`
+
+##### TC-008: Error Path — Returns 404 When ID Not Found
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Path Params**: `id` = valid but non-existent GUID
+- **Expected Response**:
+  - Status: 404 Not Found
+- **Assertions**:
+  - Response status is 404
+- **AC Reference**: N/A
+- **Test Method Name**: `GetById_Users_Returns404_WhenNotFound`
+
+#### PUT /api/users/{id} — Update User
+
+##### TC-009: Happy Path — Updates User
+- **Endpoint**: `PUT /api/users/{id}`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "name": "Updated Name"
+  }
+  ```
+- **Expected Response**:
+  - Status: 200 OK
+  - Body contains updated user
+- **Assertions**:
+  - Response status is 200
+  - `name` matches request
+- **AC Reference**: N/A
+- **Test Method Name**: `Put_Users_Returns200_WhenValidUpdate`
+
+##### TC-010: Validation — Returns 400 When Name Empty
+- **Endpoint**: `PUT /api/users/{id}`
+- **Auth**: Required
+- **Request Body**:
+  ```json
+  {
+    "name": ""
+  }
+  ```
+- **Expected Response**:
+  - Status: 400 Bad Request
+- **Assertions**:
+  - Response status is 400
+- **AC Reference**: N/A
+- **Test Method Name**: `Put_Users_Returns400_WhenNameEmpty`
+
+#### DELETE /api/users/{id} — Delete User
+
+##### TC-011: Happy Path — Deletes User
+- **Endpoint**: `DELETE /api/users/{id}`
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 204 No Content
+- **Assertions**:
+  - Response status is 204
+  - Subsequent GET returns 404
+- **AC Reference**: N/A
+- **Test Method Name**: `Delete_Users_Returns204_WhenExists`
+
+##### TC-012: Authorization — Returns 403 When Deleting Self
+- **Endpoint**: `DELETE /api/users/{id}` where id = current user's id
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 403 Forbidden
+- **Assertions**:
+  - Response status is 403
+  - Error message indicates cannot delete own account
+- **AC Reference**: N/A
+- **Test Method Name**: `Delete_Users_Returns403_WhenDeletingSelf`
+
+---
+
+## Story-Specific Test Cases (Optional)
+
+> Nếu spec được generate từ Story, thêm AC mapping ở đây.
+
+| AC ID | AC Description | Test Case IDs |
+|-------|----------------|---------------|
+| AC-1 | {Given...When...Then...} | TC-001, TC-002 |
+| AC-2 | {Given...When...Then...} | TC-004, TC-005 |
+
+---
+
+## Regression Tests (Optional)
+
+> Test cases cho bugs đã được tìm thấy và fix.
+
+| Bug ID | Description | Test Case ID | Date Added |
+|--------|-------------|--------------|------------|
+| BUG-001 | User profile missing notification_settings field | TC-R001 | 2024-01-15 |
+
+### TC-R001: BUG-001 Regression — notification_settings Present in Response
+- **Endpoint**: `GET /api/users/{id}`
+- **Auth**: Required
+- **Expected Response**:
+  - Status: 200 OK
+  - Body includes `notification_settings` field
+- **Assertions**:
+  - `notification_settings` is present and not undefined
+- **Test Method Name**: `BUG_R001_NotificationSettings_IsPresent`
+
+---
+
+## Changelog
+
+| Date | Version | Changes | Author |
+|------|---------|---------|--------|
+| [created_date] | v1 | Initial API test specification | @[executor] |
+| [updated_date] | v2 | Added endpoints for user management | @[executor] |
+
+---
+
+## AI Usage Log
+
+| # | Date | Command | Input (est.) | Output (est.) |
+|---|------|---------|-------------|---------------|
+| 1 | [created_date] | /tas-apitest-plan | ~{N}k | ~{N}k |
+| **Total** | | | **~{N}k** | **~{N}k** |