universal-dev-standards 5.1.0-beta.6 → 5.1.0-beta.7

package/bundled/locales/zh-TW/core/packaging-standards.md

@@ -0,0 +1,224 @@
+---
+source: ../../../core/packaging-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-04-15
+status: current
+---
+
+# 打包標準
+
+> **語言**: [English](../../../core/packaging-standards.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-04-15
+**適用性**: 使用 UDS/DevAP 工具鏈的專案
+**範圍**: 通用 (Universal)
+
+---
+
+## 目的
+
+本標準定義一套基於 Recipe 的打包框架，讓使用者專案可在 `.devap/packaging.yaml` 中宣告打包目標（target）。UDS 負責提供 Recipe 定義與內建 Recipe 函式庫；DevAP 則在 pipeline 中執行編排。
+
+框架的關注點分離如下：
+- **使用者專案**：宣告「打包什麼」（targets + 設定覆蓋）
+- **UDS**：定義「如何打包」（Recipe 結構 + 內建 Recipes）
+- **DevAP**：執行「何時打包」（在 Review 與 Deploy 之間的 pipeline 階段）
+
+---
+
+## 核心原則
+
+| 原則 | 說明 |
+|------|------|
+| **Recipe-based** | 每個打包目標都參照一個具名 Recipe；不在 pipeline YAML 中撰寫臨時腳本 |
+| **宣告式 targets** | 專案在 `.devap/packaging.yaml` 中宣告 targets；DevAP 負責解析與執行 |
+| **可客製化** | 四個客製化層允許設定覆蓋、Hook 注入、自訂 Recipe 及 Escape Hatch |
+| **整合至 Pipeline** | 打包作為獨立階段運行於 VibeOps pipeline 的 Review 與 Deploy 之間 |
+
+---
+
+## Recipe 結構
+
+Recipe 是定義如何打包專案的 YAML 檔案，欄位定義如下：
+
+```yaml
+# Recipe: <name>.yaml
+name: <string>            # 必填 — 唯一識別符（kebab-case）
+description: <string>     # 選填 — 人類可讀描述
+requires:                 # 選填 — 執行前必須存在的檔案
+  - <file-path>
+steps:                    # 必填 — 有序的建置/打包步驟清單
+  - run: <shell-command>
+    description: <string> # 選填 — 步驟描述
+config:                   # 選填 — 預設設定值（可被使用者專案覆蓋）
+  <key>: <value>
+hooks:                    # 選填 — 生命週期 hooks（~ 表示不執行）
+  preBuild: ~
+  postBuild: ~
+  prePublish: ~
+  postPublish: ~
+```
+
+### 必填與選填欄位
+
+| 欄位 | 必填 | 說明 |
+|------|------|------|
+| `name` | 是 | 唯一識別符，kebab-case 格式 |
+| `steps` | 是 | 至少需要一個步驟 |
+| `description` | 否 | 人類可讀描述 |
+| `requires` | 否 | 前置條件檔案檢查 |
+| `config` | 否 | 預設設定值；所有 key 均可被使用者專案覆蓋 |
+| `hooks` | 否 | 生命週期 hook 插入點；`~` 表示不執行 |
+
+### 步驟變數
+
+設定值與執行時期情境可在 `run` 指令中使用 `{variable}` 占位符：
+
+| 變數 | 來源 | 範例 |
+|------|------|------|
+| `{registry}` | `config.registry` | `ghcr.io` |
+| `{name}` | `package.json#name` 或 `config.name` | `my-app` |
+| `{version}` | `package.json#version` 或 `config.version` | `1.2.3` |
+| `{platforms}` | `config.platforms` | `linux/amd64,linux/arm64` |
+| `{output_dir}` | `config.output_dir` | `dist/installers` |
+
+---
+
+## 內建 Recipes
+
+UDS 隨附四個內建 Recipe，位於 `recipes/` 目錄：
+
+| Recipe | 檔案 | 使用場景 |
+|--------|------|----------|
+| `npm-library` | `recipes/npm-library.yaml` | 不含執行入口的 npm 套件 |
+| `npm-cli` | `recipes/npm-cli.yaml` | 含 `bin` 欄位的 npm 套件（CLI 工具） |
+| `docker-service` | `recipes/docker-service.yaml` | Docker 容器映像建置與推送 |
+| `windows-installer` | `recipes/windows-installer.yaml` | Windows 安裝程式（.msi / .exe）透過使用者腳本 |
+
+### 選擇 Recipe 的決策流程
+
+```
+產出物是 npm 套件嗎？
+├── 是 → package.json 是否含有 "bin" 欄位？
+│         ├── 是 → npm-cli
+│         └── 否 → npm-library
+└── 否 → 產出物是容器映像嗎？
+          ├── 是 → docker-service
+          └── 否 → 產出物是 Windows 安裝程式嗎？
+                    ├── 是 → windows-installer
+                    └── 否 → 撰寫自訂 Recipe（參見客製化層）
+```
+
+---
+
+## 客製化層
+
+需要偏離內建 Recipe 預設值的專案，應使用最低適用層：
+
+| 層級 | 機制 | 使用時機 |
+|------|------|----------|
+| **L1 — 設定覆蓋** | `.devap/packaging.yaml` 中的 `config:` 區塊 | 更改預設值（registry URL、tag、輸出目錄）|
+| **L2 — Hook 注入** | `.devap/packaging.yaml` 中的 `hooks:` 區塊 | 在建置或發佈前後執行額外指令 |
+| **L3 — 自訂 Recipe** | 專案 `.devap/recipes/` 中的新 `.yaml` 檔案 | 完全不同的建置流程；內建 Recipe 不適用 |
+| **L4 — Escape Hatch** | target 定義中以 `script:` 取代 `recipe:` | 原始 shell 腳本，無適合的 Recipe 抽象 |
+
+### L1 範例 — 設定覆蓋
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: publish-npm
+    recipe: npm-library
+    config:
+      registry: https://npm.pkg.github.com
+      access: restricted
+      tag: beta
+```
+
+### L2 範例 — Hook 注入
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: docker-push
+    recipe: docker-service
+    hooks:
+      postPush: |
+        curl -X POST https://hooks.example.com/deploy-notify \
+          -d "{\"version\": \"{version}\"}"
+```
+
+### L3 範例 — 自訂 Recipe
+
+```yaml
+# .devap/recipes/electron-app.yaml
+name: electron-app
+description: 建置 Electron 桌面應用程式
+requires:
+  - package.json
+  - electron-builder.yml
+steps:
+  - run: npm run build
+  - run: npx electron-builder --publish never
+config:
+  output_dir: dist
+```
+
+### L4 範例 — Escape Hatch
+
+```yaml
+# .devap/packaging.yaml
+targets:
+  - name: legacy-bundle
+    script: |
+      ./scripts/legacy-bundle.sh
+      mv output/ dist/bundle/
+```
+
+---
+
+## 打包驗收標準
+
+當以下**所有**條件均滿足時，打包執行視為**成功**：
+
+| 標準 | 閾值 | 備註 |
+|------|------|------|
+| 所有 `requires` 檔案存在 | 100% | 在任何步驟執行前檢查 |
+| 所有步驟以 exit code 0 結束 | 100% | 任何非零 exit 使執行失敗 |
+| `postBuild` 產出物存在 | 存在於預期路徑 | 建置步驟後由 DevAP 驗證 |
+| Hook 指令以 exit code 0 結束 | 100% | Hook 失敗會傳播為步驟失敗 |
+| 已發佈產出物可被取回 | HTTP 200 / registry 查詢成功 | 由 DevAP 在發佈後進行 smoke check |
+
+### 失敗處理
+
+| 失敗類型 | 行動 | 可重試？ |
+|----------|------|----------|
+| `requires` 檔案缺失 | 立即失敗，回報缺失路徑 | 否 |
+| 步驟非零 exit | 立即失敗，若已定義則執行 `postBuild` hook | 可設定（預設：否）|
+| Hook 非零 exit | 立即失敗 | 否 |
+| 發佈無法連線 | 以指數退避重試最多 3 次 | 是（3×）|
+
+---
+
+## 相關標準
+
+- [部署標準](deployment-standards.md) — 打包後的部署階段
+- [Pipeline 整合標準](pipeline-integration-standards.md) — CI/CD pipeline 設定
+- [Check-in 標準](checkin-standards.md) — 打包前的品質關卡
+- [版本控制標準](versioning.md) — 套件產出物使用的版本號
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-04-15 | 初始發行 — XSPEC-034 Phase 1 |
+
+---
+
+## 授權
+
+本標準以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。

package/bundled/skills/e2e-assistant/SKILL.md

@@ -53,11 +53,25 @@ Scan coverage gaps between BDD features and existing E2E tests.
 
 ## Supported Frameworks | 支援框架
 
-| Framework | Auto-detected | Template |
-|-----------|:------------:|----------|
-| Playwright | ✅ | `@playwright/test` |
-| Cypress | ✅ | `cy.*` commands |
-| Vitest | ✅ | `describe/it` + async |
+| Ecosystem | Framework | Auto-detected | Detection signal |
+|-----------|-----------|:------------:|----------|
+| JavaScript | Playwright | ✅ | `@playwright/test` in package.json |
+| JavaScript | Cypress | ✅ | `cypress` dep + config file |
+| JavaScript | Vitest | ✅ | `vitest` dep + e2e directory |
+| JavaScript | WebdriverIO | ❌ Manual | listed in SUPPORTED_FRAMEWORKS |
+| Python | pytest-playwright | ✅ | `pytest-playwright` in requirements |
+| Python | Selenium + pytest | ✅ | `selenium` in requirements |
+| Python | Robot Framework | ✅ | `robotframework` in requirements |
+| Python | Behave | ✅ | `behave` in requirements |
+| Go | chromedp | ✅ | `chromedp` in go.mod |
+| Go | rod | ✅ | `rod` in go.mod |
+| Java | Selenium WebDriver | ✅ | `selenium-java` in pom.xml / build.gradle |
+| Java | Playwright for Java | ✅ | `playwright` in pom.xml / build.gradle |
+| Java | Gauge | ✅ | `gauge-java` in pom.xml / build.gradle |
+| Ruby | Capybara | ✅ | `capybara` in Gemfile |
+| Ruby | Watir | ✅ | `watir` in Gemfile |
+| C# | Playwright for .NET | ❌ Manual | not yet auto-detected |
+| C# | Selenium WebDriver | ❌ Manual | not yet auto-detected |
 
 ## Usage | 使用方式
 

package/bundled/skills/testing-guide/SKILL.md

@@ -96,6 +96,7 @@ For complete standards, see:
 - [Testing Standards](../../core/testing-standards.md) - Actionable rules
 - [Testing Theory](./testing-theory.md) - Educational knowledge base
 - [Testing Pyramid](./testing-pyramid.md) - Detailed pyramid ratios
+- [Test Skeleton Templates](./test-skeleton-templates.md) - Multi-language skeletons for UT/IT/ST/Perf/Contract
 
 ### AI-Optimized Format (Token-Efficient)
 
@@ -109,6 +110,10 @@ For AI assistants, use the YAML format files for reduced token usage:
   - Integration Testing: `ai/options/testing/integration-testing.ai.yaml`
   - System Testing: `ai/options/testing/system-testing.ai.yaml`
   - E2E Testing: `ai/options/testing/e2e-testing.ai.yaml`
+  - Security Testing: `ai/options/testing/security-testing.ai.yaml`
+  - Performance Testing: `ai/options/testing/performance-testing.ai.yaml`
+  - Contract Testing: `ai/options/testing/contract-testing.ai.yaml`
+- Skeleton templates (all levels, multi-language): [test-skeleton-templates.md](./test-skeleton-templates.md)
 
 ## Naming Conventions
 

package/bundled/skills/testing-guide/test-skeleton-templates.md

@@ -0,0 +1,316 @@
+# Test Skeleton Templates | 測試骨架模板
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/testing-guide/test-skeleton-templates.md)
+
+**Version**: 2.0.0
+**Last Updated**: 2026-04-14
+
+Language-agnostic test skeleton patterns for all testing pyramid levels.
+AI should read `uds.project.yaml` at runtime to determine the target ecosystem,
+then generate code using the appropriate framework for that language.
+
+---
+
+## How to Use This Document | 如何使用本文件
+
+This document contains **patterns only** — pseudocode that applies to any language.
+
+**AI workflow for generating tests:**
+1. Read `uds.project.yaml` to identify `ecosystem` (e.g. `python`, `go`, `java`, `rust`)
+2. Select the test framework standard for that ecosystem (e.g. pytest, testing, JUnit, #[test])
+3. Apply the pseudocode pattern below, translated into the target language
+4. Fill in `[TODO]` markers with real implementation details
+
+> If `uds.project.yaml` is not present, ask the user for their language/framework before generating.
+
+---
+
+## Unit Test (UT) | 單元測試
+
+**Purpose**: Test a single function/method in isolation — no external dependencies.
+**Speed**: < 100ms per test.
+**Isolation**: Complete (use stubs/mocks for all dependencies).
+
+### Pattern: Arrange-Act-Assert
+
+```
+# [TODO: Replace with target language syntax]
+# Arrange
+subject = new TargetClass()
+input   = <test_value>
+
+# Act
+result = subject.method(input)
+
+# Assert
+assert result == <expected_value>
+```
+
+### Pattern: Error / Edge Case
+
+```
+# [TODO: Replace with target language syntax]
+# Assert that invalid input raises / returns error
+assert throws_error( subject.method(invalid_input) )
+```
+
+### Naming convention
+```
+methodName_scenario_expectedResult
+# Examples:
+#   calculateTotal_withEmptyCart_returnsZero
+#   validateEmail_withInvalidFormat_returnsFalse
+```
+
+### AI generation instruction
+> Read `uds.project.yaml → ecosystem`, then:
+> - Wrap the above pseudocode in the ecosystem's test runner structure
+> - Use the ecosystem's assertion library
+> - Use the ecosystem's mock/stub mechanism for dependencies
+> - Apply the ecosystem's file naming convention (e.g. `_test.go`, `*_spec.rb`, `Test*.java`)
+
+---
+
+## Integration Test (IT) | 整合測試
+
+**Purpose**: Test the boundary between two components (DB, HTTP, queue).
+**Speed**: < 1 second per test.
+**Isolation**: Partial — use real implementations when possible, stubs for external services.
+
+### Pattern: Database Integration
+
+```
+# [TODO: Replace with target language syntax]
+# Arrange — start test database (in-memory or container)
+db   = start_test_database()
+repo = new Repository(db)
+
+# Act
+repo.save(entity)
+found = repo.findById(entity.id)
+
+# Assert
+assert found == entity
+
+# Teardown — rollback or truncate
+db.cleanup()
+```
+
+### Pattern: HTTP API Integration
+
+```
+# [TODO: Replace with target language syntax]
+# Act
+response = http_client.post("/api/resource", body = { key: value })
+
+# Assert
+assert response.status == 201
+assert response.body contains expected_fields
+```
+
+### Pattern: Message Queue Integration
+
+```
+# [TODO: Replace with target language syntax]
+# Act
+publisher.send("topic.created", event)
+received = consumer.receive(timeout = 5s)
+
+# Assert
+assert received.payload == event
+```
+
+### AI generation instruction
+> Read `uds.project.yaml → ecosystem`, then select the appropriate:
+> - In-memory or Testcontainers-compatible DB driver for that ecosystem
+> - HTTP test client for that ecosystem
+> - Embedded queue or mock transport for that ecosystem
+> Never hardcode a specific library — choose based on detected ecosystem.
+
+---
+
+## System Test (ST) | 系統測試
+
+**Purpose**: Test a complete business flow within one subsystem, with external services stubbed.
+**Isolation**: Stub all external HTTP/queue calls; use real DB.
+
+### Pattern: Full Flow with Stubbed External Service
+
+```
+# [TODO: Replace with target language syntax]
+# Arrange — stub external dependency
+stub_server = start_http_stub("/external-api/charge",
+    response = { status: "approved", id: "TX-001" })
+
+# Boot subsystem under test
+app = start_system(config = { external_url: stub_server.url })
+
+# Act
+result = app.run_flow(input_data)
+
+# Assert
+assert result.status == "confirmed"
+assert result.id is not null
+
+# Teardown
+stub_server.stop()
+app.stop()
+```
+
+### AI generation instruction
+> Read `uds.project.yaml → ecosystem`, then select the appropriate:
+> - HTTP stub/mock server for that ecosystem (e.g. WireMock, MSW, responses, httpretty, httpmock)
+> - Application test harness / test client for that framework
+> Never hardcode a specific stub library — choose based on detected ecosystem.
+
+---
+
+## Performance Test | 效能測試
+
+**Purpose**: Validate throughput, latency, and resource usage under load.
+**Focus**: SLOs — p95 latency target, requests-per-second target, error rate threshold.
+
+### Pattern: Load Test
+
+```
+# [TODO: Replace with target load testing tool syntax]
+# Configuration
+rate     = <RPS target>          # [TODO] e.g. 50 requests/sec
+duration = <test duration>       # [TODO] e.g. 60 seconds
+target   = "<API_URL>/api/resource"
+
+# Thresholds
+p95_latency_threshold = <ms>     # [TODO] e.g. 500ms
+error_rate_threshold  = <rate>   # [TODO] e.g. 1%
+
+# Execute
+results = run_load_test(rate, duration, target)
+
+# Assert
+assert results.p95_latency < p95_latency_threshold
+assert results.error_rate  < error_rate_threshold
+```
+
+### AI generation instruction
+> Read `uds.project.yaml → ecosystem`, then select the appropriate load testing tool:
+> - Performance tests are **language-independent by default** (k6, Gatling, Locust, vegeta, wrk)
+> - Prefer the tool already present in the project (check for existing config files)
+> - If none present, suggest the most common tool for the detected ecosystem
+> Set `[TODO]` thresholds based on the project's SLO definition if available.
+
+---
+
+## Contract Test | 合約測試
+
+**Purpose**: Verify API contracts between consumer and provider without deploying both.
+**When**: Microservices, shared APIs, CI on every PR.
+
+### Pattern: Consumer Contract (Consumer-Driven)
+
+```
+# [TODO: Replace with target language / Pact version syntax]
+# Define the contract
+pact = new ConsumerPactBuilder(
+    consumer = "[ConsumerName]",   # [TODO]
+    provider = "[ProviderName]"    # [TODO]
+)
+
+pact.given("resource 123 exists")
+    .upon_receiving("a GET request for resource 123")
+    .with_request(method = GET, path = "/resources/123")
+    .will_respond_with(
+        status = 200,
+        body   = { id: like("123"), name: like("Alice") }  # [TODO] add fields
+    )
+
+# Run consumer test against mock provider
+pact.run_test(lambda mock_url:
+    client = new ApiClient(mock_url)
+    resource = client.get_resource("123")
+    assert resource.id == "123"
+)
+```
+
+### Pattern: Provider Verification
+
+```
+# [TODO: Replace with target language / Pact version syntax]
+# Verify all consumer pacts against the real provider
+verifier = new ProviderVerifier(
+    provider_url  = "http://localhost:[PORT]",  # [TODO]
+    pact_broker   = env("PACT_BROKER_URL"),
+    provider_name = "[ProviderName]",           # [TODO]
+    state_handlers = {
+        "resource 123 exists": lambda: seed_database(id = "123")  # [TODO]
+    }
+)
+verifier.verify()
+```
+
+### Pattern: OpenAPI / Schema Contract Test
+
+```
+# [TODO: Replace with target language syntax]
+# Load OpenAPI spec and validate responses
+spec    = load_openapi_spec("./api/openapi.yaml")  # [TODO] spec path
+server  = start_test_server()
+
+for each critical_endpoint in spec.paths:
+    response = http_client.request(critical_endpoint)
+    assert spec.validates(critical_endpoint, response)
+```
+
+### AI generation instruction
+> Read `uds.project.yaml → ecosystem`, then select:
+> - Consumer-Driven: Pact has SDKs for most languages — use the SDK for the detected ecosystem
+> - OpenAPI: Use the OpenAPI validation library available for the detected ecosystem
+> Never hardcode a specific Pact version or library — choose based on detected ecosystem.
+
+---
+
+## Choosing the Right Test Level | 選擇正確的測試層
+
+```
+Use UT when:
+  ✓ Testing a single function or method
+  ✓ All dependencies can be replaced by stubs
+  ✓ Should run in < 100ms
+
+Use IT when:
+  ✓ Testing interaction with a real DB, HTTP endpoint, or message queue
+  ✓ Crossing a component boundary
+  ✓ Needs a real or containerised dependency
+
+Use ST when:
+  ✓ Testing a complete business flow within one subsystem
+  ✓ External services should be stubbed (not mocked)
+  ✓ Validates non-functional requirements (latency, throughput)
+
+Use E2E when:
+  ✓ Testing a full user journey across multiple systems
+  ✓ Uses a production-like environment
+  ✓ Critical paths only (top 5–10 journeys)
+
+Use Performance when:
+  ✓ Validating SLOs before production
+  ✓ Checking throughput or latency under load
+
+Use Contract when:
+  ✓ Two services share an API contract
+  ✓ You want CI to catch consumer/provider drift early
+```
+
+---
+
+## Related Documents | 相關文件
+
+- [Testing Pyramid](./testing-pyramid.md)
+- [E2E Assistant](../e2e-assistant/SKILL.md)
+- [Contract Test Assistant](../contract-test-assistant/SKILL.md)
+- Core: [testing-standards.md](../../core/testing-standards.md)
+- Options:
+  - [unit-testing.ai.yaml](../../.standards/options/testing/unit-testing.ai.yaml)
+  - [integration-testing.ai.yaml](../../.standards/options/testing/integration-testing.ai.yaml)
+  - [system-testing.ai.yaml](../../.standards/options/testing/system-testing.ai.yaml)
+  - [performance-testing.ai.yaml](../../.standards/options/testing/performance-testing.ai.yaml)
+  - [contract-testing.ai.yaml](../../.standards/options/testing/contract-testing.ai.yaml)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.1.0-beta.6",
+  "version": "5.1.0-beta.7",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/commands/config.js

@@ -562,6 +562,8 @@ export async function runProjectConfiguration(options) {
     }
 
     baseChoices.push(
+      new DynSeparator(),
+      { name: t('config.projectContractOption', 'Project Command Contract (uds.project.yaml)'), value: 'project_contract' },
       new DynSeparator(),
       { name: t('config.vibeMode', 'Vibe Coding Mode'), value: 'vibe_coding' },
       new DynSeparator(),
@@ -588,6 +590,13 @@ export async function runProjectConfiguration(options) {
     process.exit(0);
   }
 
+  // Handle project_contract — guided uds.project.yaml creation (XSPEC-029 Phase 3)
+  if (configType === 'project_contract') {
+    const { promptProjectCommandContract } = await import('../prompts/init.js');
+    await promptProjectCommandContract(projectPath);
+    process.exit(0);
+  }
+
   // Handle show (flat menu item)
   if (configType === 'show') {
     const currentConfig = config.init();