universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/skills/claude-code/testing-guide/testing-pyramid.md

@@ -0,0 +1,440 @@
+# Testing Pyramid Guide
+
+> **Language**: English | [繁體中文](../../../locales/zh-TW/skills/claude-code/testing-guide/testing-pyramid.md)
+
+**Version**: 1.1.0
+**Last Updated**: 2025-12-29
+**Applicability**: Claude Code Skills
+
+---
+
+## Purpose
+
+This document provides detailed guidelines for the testing pyramid and test writing best practices. It supports both ISTQB and Industry Pyramid frameworks.
+
+---
+
+## Framework Selection
+
+| Framework | Levels | Best For |
+|-----------|--------|----------|
+| **ISTQB** | UT → IT/SIT → ST → AT/UAT | Enterprise, compliance, formal QA |
+| **Industry Pyramid** | UT (70%) → IT (20%) → E2E (10%) | Agile, DevOps, CI/CD |
+
+**Note on Integration Testing abbreviation:**
+- **IT** (Integration Testing): Agile/DevOps communities
+- **SIT** (System Integration Testing): Enterprise/ISTQB contexts
+- Both refer to the same testing level
+
+---
+
+## Unit Testing (UT)
+
+### Definition
+
+Tests individual functions, methods, or classes in isolation from external dependencies.
+
+### Characteristics
+
+- **Isolated**: No database, network, or file system access
+- **Fast**: Each test < 100ms
+- **Deterministic**: Same input always produces same output
+
+### Scope
+
+```
+✅ Single function/method
+✅ Single class
+✅ Pure business logic
+✅ Data transformations
+✅ Validation rules
+
+❌ Database queries
+❌ External API calls
+❌ File I/O operations
+❌ Multi-class interactions
+```
+
+### Example
+
+```typescript
+describe('UserValidator', () => {
+    let validator: UserValidator;
+
+    beforeEach(() => {
+        validator = new UserValidator();
+    });
+
+    it('should return true for valid email format', () => {
+        const result = validator.validateEmail('user@example.com');
+        expect(result).toBe(true);
+    });
+
+    it('should return false for invalid email format', () => {
+        const result = validator.validateEmail('invalid-email');
+        expect(result).toBe(false);
+    });
+});
+```
+
+---
+
+## Integration Testing (IT/SIT)
+
+### Definition
+
+Tests interactions between multiple components, modules, or external systems.
+
+**Abbreviation Note:**
+- **IT** (Integration Testing): Common in Agile/DevOps communities (Martin Fowler, Google)
+- **SIT** (System Integration Testing): Common in Enterprise/ISTQB contexts
+- Both terms refer to the same testing concept
+
+### When Integration Tests Are Required
+
+| Scenario | Reason |
+|----------|--------|
+| Query predicates | Mocks cannot verify filter expressions |
+| Entity relationships | Verify foreign key correctness |
+| Composite keys | In-memory DB may differ from real DB |
+| Field mapping | DTO ↔ Entity transformations |
+| Pagination | Row ordering and counting |
+| Transactions | Rollback behavior |
+
+**Decision Rule**: If your unit test uses a wildcard matcher (`any()`, `It.IsAny<>`, `Arg.Any<>`) for a query/filter parameter, that functionality MUST have an integration test.
+
+### Characteristics
+
+- **Component Integration**: Tests module boundaries
+- **Real Dependencies**: Uses actual databases, APIs (often containerized)
+- **Slower**: Each test typically 1-10 seconds
+
+### Scope
+
+```
+✅ Database CRUD operations
+✅ Repository + Database
+✅ Service + Repository
+✅ API endpoint + Service layer
+✅ Message queue producers/consumers
+✅ Cache read/write operations
+
+❌ Full user workflows
+❌ Cross-service communication
+❌ UI interactions
+```
+
+### Example
+
+```typescript
+describe('UserRepository Integration', () => {
+    let repository: UserRepository;
+    let dbContext: TestDbContext;
+
+    beforeEach(async () => {
+        dbContext = await TestDbContext.create();
+        repository = new UserRepository(dbContext);
+    });
+
+    afterEach(async () => {
+        await dbContext.dispose();
+    });
+
+    it('should persist user to database', async () => {
+        const user = { name: 'Test User', email: 'test@example.com' };
+
+        await repository.create(user);
+        const saved = await repository.getById(user.id);
+
+        expect(saved).not.toBeNull();
+        expect(saved.name).toBe('Test User');
+    });
+});
+```
+
+---
+
+## System Testing (ST)
+
+### Definition
+
+Tests the complete integrated system to verify it meets specified requirements.
+
+### Characteristics
+
+- **Complete System**: All components deployed and integrated
+- **Requirement-Based**: Tests against functional specifications
+- **Production-Like**: Uses environment similar to production
+
+### Scope
+
+```
+✅ Complete API workflows
+✅ Cross-service transactions
+✅ Data flow through entire system
+✅ Security requirements
+✅ Performance under load
+✅ Error handling & recovery
+
+❌ UI visual testing
+❌ User journey simulations
+❌ A/B testing scenarios
+```
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| Functional | Verify features work as specified |
+| Performance | Load, stress, scalability testing |
+| Security | Penetration, vulnerability scanning |
+| Reliability | Failover, recovery, stability |
+
+---
+
+## End-to-End Testing (E2E)
+
+### Definition
+
+Tests complete user workflows from the user interface through all system layers.
+
+### Characteristics
+
+- **User Perspective**: Simulates real user interactions
+- **Full Stack**: UI → API → Database → External Services
+- **Slowest**: Each test typically 30 seconds to several minutes
+
+### Scope
+
+```
+✅ Critical user journeys
+✅ Login/Authentication flows
+✅ Core business transactions
+✅ Cross-browser functionality
+✅ Smoke tests for deployments
+
+❌ Every possible user path
+❌ Edge cases (use UT/IT)
+❌ Performance benchmarking
+```
+
+### Example (Playwright)
+
+```typescript
+test.describe('User Registration Journey', () => {
+    test('should complete registration and login', async ({ page }) => {
+        // Navigate to registration
+        await page.goto('/register');
+
+        // Fill form
+        await page.fill('[data-testid="email"]', 'new@example.com');
+        await page.fill('[data-testid="password"]', 'SecurePass123!');
+        await page.click('[data-testid="register-button"]');
+
+        // Verify success
+        await expect(page.locator('[data-testid="success-message"]'))
+            .toContainText('Registration successful');
+
+        // Login with new account
+        await page.goto('/login');
+        await page.fill('[data-testid="email"]', 'new@example.com');
+        await page.fill('[data-testid="password"]', 'SecurePass123!');
+        await page.click('[data-testid="login-button"]');
+
+        // Verify dashboard
+        await expect(page).toHaveURL('/dashboard');
+    });
+});
+```
+
+---
+
+## Test Environment Isolation
+
+### Virtual Environments
+
+| Language | Tools | Lock File |
+|----------|-------|----------|
+| Python | venv, poetry | requirements.txt, poetry.lock |
+| Node.js | nvm + npm | package-lock.json |
+| Ruby | rbenv, bundler | Gemfile.lock |
+| Java | SDKMAN, Maven | pom.xml |
+| .NET | dotnet SDK | packages.lock.json |
+| Go | go mod | go.sum |
+
+### Containerized Testing
+
+| Test Level | Container Usage |
+|------------|----------------|
+| UT | ❌ Not needed - use mocks |
+| IT | ✅ Testcontainers for DB, cache |
+| ST | ✅ Docker Compose for full env |
+| E2E | ✅ Full containerized stack |
+
+### Testcontainers Example
+
+```typescript
+import { PostgreSqlContainer } from 'testcontainers';
+
+describe('Database Integration', () => {
+    let container: PostgreSqlContainer;
+
+    beforeAll(async () => {
+        container = await new PostgreSqlContainer().start();
+    });
+
+    afterAll(async () => {
+        await container.stop();
+    });
+
+    test('should connect to database', async () => {
+        const connectionUrl = container.getConnectionUri();
+        // Use connectionUrl for tests
+    });
+});
+```
+
+---
+
+## Mock Limitations
+
+### Query Predicate Verification
+
+When mocking repository methods that accept query predicates (e.g., lambda expressions, filter functions), using wildcard matchers like `any()` ignores the actual query logic, allowing incorrect queries to pass unit tests.
+
+```typescript
+// ❌ Jest mock ignores actual filter
+jest.spyOn(repo, 'findBy').mockResolvedValue(users);
+
+// ✓ Verify with integration test
+```
+
+**Rule of Thumb**: If your unit test mocks a method that accepts a query/filter/predicate parameter, you MUST have a corresponding integration test to verify the query logic.
+
+---
+
+## Test Data Management
+
+### Principles
+
+1. **Isolation**: Each test manages its own data
+2. **Cleanup**: Tests clean up after themselves
+3. **Determinism**: Tests don't depend on shared state
+4. **Readability**: Test data clearly shows intent
+
+### Distinct Identifiers
+
+When entities have both a surrogate key (auto-generated ID) and a business identifier (e.g., employee number, department code), test data MUST use different values for each.
+
+```typescript
+// ❌ Wrong: id equals businessCode - mapping errors go undetected
+const dept = { id: 1, businessCode: 1 };
+
+// ✓ Correct: distinct values catch field mapping bugs
+const dept = { id: 1, businessCode: 1001 };
+```
+
+### Composite Keys
+
+For entities with composite primary keys, ensure each record has a unique key combination.
+
+```typescript
+// ❌ Key collision - same (id, timestamp) combination
+const record1 = { id: 0, timestamp: now };
+const record2 = { id: 0, timestamp: now };  // Conflict!
+
+// ✓ Unique combinations
+const record1 = { id: 0, timestamp: addSeconds(now, 1) };
+const record2 = { id: 0, timestamp: addSeconds(now, 2) };
+```
+
+### Builder Pattern
+
+```typescript
+class UserBuilder {
+    private name = 'Default User';
+    private email = 'default@example.com';
+    private isActive = true;
+
+    withName(name: string): this {
+        this.name = name;
+        return this;
+    }
+
+    withEmail(email: string): this {
+        this.email = email;
+        return this;
+    }
+
+    inactive(): this {
+        this.isActive = false;
+        return this;
+    }
+
+    build(): User {
+        return { name: this.name, email: this.email, isActive: this.isActive };
+    }
+}
+
+// Usage
+const activeUser = new UserBuilder().withName('Active').build();
+const inactiveUser = new UserBuilder().inactive().build();
+```
+
+---
+
+## Quick Reference Card
+
+### Industry Pyramid (Recommended for Agile/DevOps)
+
+```
+┌──────────┬──────────────────────────────────────────┐
+│   UT     │ Single unit, isolated, mocked deps, < 100ms     │
+├──────────┼──────────────────────────────────────────┤
+│ IT/SIT   │ Component integration, real DB, 1-10 sec        │
+├──────────┼──────────────────────────────────────────┤
+│  E2E     │ User journeys, UI to DB, critical paths only    │
+└──────────┴──────────────────────────────────────────┘
+
+Ratio: UT 70% | IT 20% | E2E 10%
+```
+
+### ISTQB Framework (For Enterprise/Compliance)
+
+```
+┌──────────┬──────────────────────────────────────────┐
+│   UT     │ Component testing, isolated units              │
+├──────────┼──────────────────────────────────────────┤
+│ IT/SIT   │ Integration testing, component interactions    │
+├──────────┼──────────────────────────────────────────┤
+│   ST     │ System testing, requirement validation         │
+├──────────┼──────────────────────────────────────────┤
+│ AT/UAT   │ Acceptance testing, business validation        │
+└──────────┴──────────────────────────────────────────┘
+```
+
+**Mock Rule**: If UT mocks query params → IT is REQUIRED
+
+---
+
+## Related Standards
+
+- [Testing Standards](../../../core/testing-standards.md)
+- [Code Review Checklist](../../../core/code-review-checklist.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.1.0 | 2025-12-29 | Added: Framework Selection (ISTQB/Industry Pyramid), IT/SIT abbreviation note |
+| 1.0.0 | 2025-12-24 | Added: Standard sections (Purpose, Related Standards, Version History, License) |
+
+---
+
+## License
+
+This document is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "3.5.1-beta.1",
+  "version": "3.5.1-beta.11",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",
@@ -29,6 +29,7 @@
   "files": [
     "bin",
     "src",
+    "bundled",
     "standards-registry.json",
     "README.md"
   ],
@@ -42,7 +43,8 @@
     "test:e2e": "vitest run tests/e2e/",
     "test:all": "vitest run && vitest run tests/e2e/",
     "lint": "eslint src/",
-    "prepare": "node ../scripts/setup-husky.mjs"
+    "prepare": "node ../scripts/setup-husky.mjs",
+    "prepack": "node scripts/prepack.mjs"
   },
   "dependencies": {
     "chalk": "^5.3.0",

package/src/commands/check.js

@@ -33,7 +33,7 @@ import {
   extractMarkedContent
 } from '../utils/integration-generator.js';
 import { checkForUpdates } from '../utils/npm-registry.js';
-import { t } from '../i18n/messages.js';
+import { t, getLanguage } from '../i18n/messages.js';
 
 /**
  * Check command - verify adoption status
@@ -72,7 +72,12 @@ export async function checkCommand(options = {}) {
   console.log(chalk.green(msg.standardsInitialized));
   console.log();
   console.log(chalk.cyan(msg.adoptionStatus));
-  console.log(chalk.gray(`  ${common.level}: ${manifest.level} - ${levelInfo.name} (${levelInfo.nameZh})`));
+  const lang = getLanguage();
+  const zhName = lang === 'zh-cn' ? levelInfo.nameZhCn : levelInfo.nameZh;
+  const levelDisplay = lang === 'en'
+    ? `${manifest.level} - ${levelInfo.name}`
+    : `${manifest.level} - ${levelInfo.name} (${zhName})`;
+  console.log(chalk.gray(`  ${common.level}: ${levelDisplay}`));
   console.log(chalk.gray(`  ${msg.installed}: ${manifest.upstream.installed}`));
   console.log(chalk.gray(`  ${common.version}: ${manifest.upstream.version}`));
   console.log();
@@ -240,7 +245,7 @@ export async function checkCommand(options = {}) {
   checkIntegrationFiles(manifest, projectPath, msg);
 
   // Skills status
-  displaySkillsStatus(manifest, projectPath, msg);
+  const { missingSkills, missingCommands } = displaySkillsStatus(manifest, projectPath, msg);
 
   // Coverage report
   displayCoverageReport(manifest, msg, common);
@@ -253,6 +258,13 @@ export async function checkCommand(options = {}) {
   } else {
     console.log(chalk.yellow(msg.issuesDetected));
   }
+
+  // Show hint if Skills/Commands are missing (check is read-only, no installation)
+  if (missingSkills.length > 0 || missingCommands.length > 0) {
+    console.log();
+    console.log(chalk.cyan(msg.missingSkillsHint || 'Tip: Run `uds update` to install missing Skills/Commands'));
+  }
+
   console.log();
 }
 
@@ -643,18 +655,21 @@ async function migrateToHashBasedTracking(projectPath, manifest) {
 }
 
 /**
- * Display skills status
+ * Display skills status and return missing Skills/Commands info
+ * @returns {{missingSkills: Array, missingCommands: Array}}
  */
 function displaySkillsStatus(manifest, projectPath, msg) {
   console.log(chalk.cyan(msg.skillsStatus));
 
   const aiTools = manifest.aiTools || [];
+  const missingSkills = [];
+  const missingCommands = [];
 
   // If no AI tools configured, show basic info
   if (aiTools.length === 0) {
     console.log(chalk.gray(`  ${msg.noAiToolsConfigured || 'No AI tools configured'}`));
     console.log();
-    return;
+    return { missingSkills, missingCommands };
   }
 
   // Check for Marketplace installation (Claude Code specific)
@@ -696,7 +711,10 @@ function displaySkillsStatus(manifest, projectPath, msg) {
     const projectSkillsInfo = getInstalledSkillsInfoForAgent(tool, 'project', projectPath);
     const userSkillsInfo = getInstalledSkillsInfoForAgent(tool, 'user', projectPath);
 
-    if (projectSkillsInfo?.installed || userSkillsInfo?.installed) {
+    // Check if using marketplace for Claude Code
+    const usingMarketplace = isMarketplace && tool === 'claude-code';
+
+    if (projectSkillsInfo?.installed || userSkillsInfo?.installed || usingMarketplace) {
       console.log(chalk.green(`    ✓ Skills ${msg.installed || 'installed'}:`));
       if (userSkillsInfo?.installed) {
         console.log(chalk.gray(`      - ${msg.skillsGlobal || 'User level'}: ${userSkillsInfo.path}`));
@@ -719,6 +737,12 @@ function displaySkillsStatus(manifest, projectPath, msg) {
           console.log(chalk.gray(`      ${msg.canUseFallback || 'Can use fallback'}: ${config.fallbackSkillsPath}`));
         }
       }
+      // Track missing Skills
+      missingSkills.push({
+        agent: tool,
+        displayName,
+        paths: config.skills
+      });
     }
 
     // Check Commands installation for this agent
@@ -732,6 +756,12 @@ function displaySkillsStatus(manifest, projectPath, msg) {
         }
       } else {
         console.log(chalk.gray(`    ○ Commands: ${msg.notInstalled || 'Not installed'}`));
+        // Track missing Commands
+        missingCommands.push({
+          agent: tool,
+          displayName,
+          path: config.commands.project
+        });
       }
     }
   }
@@ -753,6 +783,8 @@ function displaySkillsStatus(manifest, projectPath, msg) {
   }
 
   console.log();
+
+  return { missingSkills, missingCommands };
 }
 
 /**

package/src/commands/init.js

@@ -384,6 +384,9 @@ export async function initCommand(options) {
       return k;
     });
 
+    // Assign normalized AI tools to manifest variable
+    aiTools = aiToolsNormalized;
+
     // Check if only skills-compatible tools are detected
     const hasSkillsCompatibleTool = aiToolsNormalized.some(t => t === 'claude-code' || t === 'opencode');
     const onlySkillsCompatibleTools = aiToolsNormalized.every(t => t === 'claude-code' || t === 'opencode');
@@ -462,6 +465,17 @@ export async function initCommand(options) {
         };
       }
     }
+
+    // Auto-install commands for detected agents that support commands
+    // This matches the interactive mode behavior where commands are checked by default
+    const commandsSupportedAgents = aiToolsNormalized.filter(tool => {
+      const config = getAgentConfig(tool);
+      return config?.commands !== null;
+    });
+
+    if (commandsSupportedAgents.length > 0) {
+      skillsConfig.commandsInstallations = commandsSupportedAgents;
+    }
   }
 
   // Configuration summary
@@ -912,13 +926,13 @@ export async function initCommand(options) {
   // Create manifest
   const repoInfo = getRepositoryInfo();
 
-  // Only record options for standards that were actually copied
-  const standardsToCopyIds = new Set(standardsToCopy.map(s => s.id));
+  // Always record options as user preferences (for Skills and future updates)
+  // Even when standards aren't copied locally (minimal scope), options should be preserved
   const manifestOptions = {
-    workflow: standardsToCopyIds.has('git-workflow') ? (standardOptions.workflow || null) : null,
-    merge_strategy: standardsToCopyIds.has('git-workflow') ? (standardOptions.merge_strategy || null) : null,
-    commit_language: standardsToCopyIds.has('commit-message') ? (standardOptions.commit_language || null) : null,
-    test_levels: standardsToCopyIds.has('testing') ? (standardOptions.test_levels || []) : []
+    workflow: standardOptions.workflow || null,
+    merge_strategy: standardOptions.merge_strategy || null,
+    commit_language: standardOptions.commit_language || null,
+    test_levels: standardOptions.test_levels || []
   };
 
   // Build integrationConfigs for manifest

package/src/commands/list.js

@@ -7,7 +7,7 @@ import {
   getCategoryInfo,
   getRepositoryInfo
 } from '../utils/registry.js';
-import { t } from '../i18n/messages.js';
+import { t, getLanguage } from '../i18n/messages.js';
 
 /**
  * List command - displays available standards
@@ -36,7 +36,12 @@ export function listCommand(options) {
     }
     standards = getStandardsByLevel(levelNum);
     const levelInfo = getLevelInfo(levelNum);
-    console.log(chalk.cyan(`${msg.showingLevel} ${levelNum}: ${levelInfo.name} (${levelInfo.nameZh})`));
+    const lang = getLanguage();
+    const zhName = lang === 'zh-cn' ? levelInfo.nameZhCn : levelInfo.nameZh;
+    const levelDisplay = lang === 'en'
+      ? `${levelNum}: ${levelInfo.name}`
+      : `${levelNum}: ${levelInfo.name} (${zhName})`;
+    console.log(chalk.cyan(`${msg.showingLevel} ${levelDisplay}`));
     console.log(chalk.gray(levelInfo.description));
     console.log();
   } else if (category) {

package/src/commands/skills.js

@@ -9,8 +9,6 @@ import { t } from '../i18n/messages.js';
 const NON_SKILL_ITEMS = [
   'README.md',
   'CONTRIBUTING.template.md',
-  'install.sh',
-  'install.ps1',
   'universal-dev-standards',
   '.manifest.json',
   '.DS_Store'