@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/test-master/references/testing-anti-patterns.md

@@ -0,0 +1,234 @@
+# Testing Anti-Patterns
+
+> Reference for: Test Master
+> Load when: test review, mock issues, test quality problems
+
+---
+
+## Core Principle
+
+> **"Test what the code does, not what the mocks do."**
+
+When tests verify mock behavior instead of actual functionality, they provide false confidence while catching zero real bugs.
+
+---
+
+## The Five Anti-Patterns
+
+### Anti-Pattern 1: Testing Mock Behavior
+
+**The Problem:** Verifying that mocks exist and were called, rather than testing actual component output.
+
+```typescript
+// ❌ BAD: Testing the mock, not the behavior
+it('should call the API', () => {
+  const mockApi = jest.fn().mockResolvedValue({ data: 'test' });
+  const service = new UserService(mockApi);
+
+  service.getUser(1);
+
+  expect(mockApi).toHaveBeenCalledWith(1); // Testing mock, not result
+});
+```
+
+```typescript
+// ✅ GOOD: Testing actual behavior
+it('should return user data from API', async () => {
+  const mockApi = jest.fn().mockResolvedValue({ id: 1, name: 'Alice' });
+  const service = new UserService(mockApi);
+
+  const user = await service.getUser(1);
+
+  expect(user.name).toBe('Alice'); // Testing actual output
+});
+```
+
+**Solution:** Test the genuine component output. If you can only verify mock calls, reconsider whether the test adds value.
+
+---
+
+### Anti-Pattern 2: Test-Only Methods in Production
+
+**The Problem:** Adding methods to production classes solely for test setup or cleanup.
+
+```typescript
+// ❌ BAD: Production code polluted with test concerns
+class UserCache {
+  private cache: Map<number, User> = new Map();
+
+  getUser(id: number): User | undefined {
+    return this.cache.get(id);
+  }
+
+  // This method exists ONLY for tests
+  _resetForTesting(): void {
+    this.cache.clear();
+  }
+}
+```
+
+```typescript
+// ✅ GOOD: Test utilities separate from production
+// production/UserCache.ts
+class UserCache {
+  private cache: Map<number, User> = new Map();
+
+  getUser(id: number): User | undefined {
+    return this.cache.get(id);
+  }
+}
+
+// test/helpers.ts
+function createFreshCache(): UserCache {
+  return new UserCache(); // Fresh instance per test
+}
+```
+
+**Solution:** Relocate cleanup logic to test utility functions. Use fresh instances per test instead of reset methods.
+
+---
+
+### Anti-Pattern 3: Mocking Without Understanding
+
+**The Problem:** Over-mocking without grasping side effects, leading to tests that pass but hide real issues.
+
+```typescript
+// ❌ BAD: Mocking everything without understanding
+it('should process order', async () => {
+  jest.mock('./inventory');
+  jest.mock('./payment');
+  jest.mock('./shipping');
+  jest.mock('./notifications');
+
+  const result = await processOrder(order);
+
+  expect(result.success).toBe(true); // What did we actually test?
+});
+```
+
+```typescript
+// ✅ GOOD: Strategic mocking with real components where possible
+it('should process order with real inventory check', async () => {
+  // Real inventory service against test database
+  const inventory = new InventoryService(testDb);
+
+  // Mock only external services
+  const payment = mockPaymentGateway();
+
+  const processor = new OrderProcessor(inventory, payment);
+  const result = await processor.process(order);
+
+  expect(result.success).toBe(true);
+  expect(await inventory.getStock(order.itemId)).toBe(originalStock - 1);
+});
+```
+
+**Solution:** Run tests with real implementations first to understand behavior. Then mock at the appropriate level - external services, not internal logic.
+
+---
+
+### Anti-Pattern 4: Incomplete Mocks
+
+**The Problem:** Partial mock responses missing downstream fields that production code expects.
+
+```typescript
+// ❌ BAD: Incomplete mock response
+const mockUserApi = jest.fn().mockResolvedValue({
+  id: 1,
+  name: 'Test User'
+  // Missing: email, createdAt, permissions, settings...
+});
+
+// Test passes, but production crashes when accessing user.email
+```
+
+```typescript
+// ✅ GOOD: Complete mock matching real API response
+const mockUserApi = jest.fn().mockResolvedValue({
+  id: 1,
+  name: 'Test User',
+  email: 'test@example.com',
+  createdAt: '2024-01-01T00:00:00Z',
+  permissions: ['read', 'write'],
+  settings: {
+    theme: 'light',
+    notifications: true
+  }
+});
+
+// Or use a factory
+const mockUserApi = jest.fn().mockResolvedValue(
+  createMockUser({ name: 'Test User' }) // Factory fills defaults
+);
+```
+
+**Solution:** Mirror complete real API response structure. Use factories to generate complete mock objects with sensible defaults.
+
+---
+
+### Anti-Pattern 5: Integration Tests as Afterthought
+
+**The Problem:** Treating testing as optional follow-up work rather than integral to development.
+
+```typescript
+// ❌ BAD: "We'll add tests later"
+// Day 1: Write 500 lines of code
+// Day 2: Write 500 more lines
+// Day 3: "We need to ship, tests can wait"
+// Day 30: Catastrophic bug in production
+// Day 31: "Why didn't we have tests?"
+```
+
+```typescript
+// ✅ GOOD: Tests are part of implementation
+// Write failing test
+it('should reject duplicate usernames', async () => {
+  await createUser({ username: 'alice' });
+
+  await expect(createUser({ username: 'alice' }))
+    .rejects.toThrow('Username already exists');
+});
+
+// Make it pass
+async function createUser(data: UserInput): Promise<User> {
+  const existing = await db.users.findByUsername(data.username);
+  if (existing) {
+    throw new Error('Username already exists');
+  }
+  return db.users.create(data);
+}
+
+// Feature AND test ship together
+```
+
+**Solution:** Follow TDD - testing is implementation, not documentation. No feature is "done" without tests.
+
+---
+
+## Detection Checklist
+
+Review your tests for these warning signs:
+
+| Warning Sign | Anti-Pattern |
+|-------------|--------------|
+| `expect(mock).toHaveBeenCalled()` without testing output | Testing mock behavior |
+| Methods starting with `_` or `ForTesting` in production | Test-only methods |
+| Every dependency is mocked | Mocking without understanding |
+| Mocks return `{ success: true }` only | Incomplete mocks |
+| Test files added weeks after feature ships | Tests as afterthought |
+
+---
+
+## Quick Reference
+
+| Anti-Pattern | Symptom | Fix |
+|-------------|---------|-----|
+| Testing mocks | Only mock assertions, no behavior tests | Assert on actual output |
+| Test-only methods | `_reset()`, `_setForTest()` in prod | Use fresh instances |
+| Over-mocking | 10+ mocks per test | Test with real deps first |
+| Incomplete mocks | Minimal stub responses | Use factories, match reality |
+| Tests as afterthought | Features ship untested | TDD from the start |
+
+---
+
+*Content adapted from [obra/superpowers](https://github.com/obra/superpowers) by Jesse Vincent (@obra), MIT License.*

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/test-master/references/unit-testing.md

@@ -0,0 +1,116 @@
+# Unit Testing
+
+> Reference for: Test Master
+> Load when: Writing unit tests, Jest, Vitest, pytest
+
+## Jest/Vitest Pattern
+
+```typescript
+describe('UserService', () => {
+  let service: UserService;
+  let mockRepo: jest.Mocked<UserRepository>;
+
+  beforeEach(() => {
+    mockRepo = { findById: jest.fn(), save: jest.fn() } as any;
+    service = new UserService(mockRepo);
+  });
+
+  afterEach(() => jest.clearAllMocks());
+
+  describe('getUser', () => {
+    it('returns user when found', async () => {
+      const user = { id: '1', name: 'Test' };
+      mockRepo.findById.mockResolvedValue(user);
+
+      const result = await service.getUser('1');
+
+      expect(result).toEqual(user);
+      expect(mockRepo.findById).toHaveBeenCalledWith('1');
+    });
+
+    it('throws NotFoundError when user not found', async () => {
+      mockRepo.findById.mockResolvedValue(null);
+
+      await expect(service.getUser('1')).rejects.toThrow(NotFoundError);
+    });
+  });
+});
+```
+
+## pytest Pattern
+
+```python
+import pytest
+from unittest.mock import Mock, AsyncMock
+
+class TestUserService:
+    @pytest.fixture
+    def mock_repo(self):
+        return Mock()
+
+    @pytest.fixture
+    def service(self, mock_repo):
+        return UserService(mock_repo)
+
+    async def test_get_user_returns_user(self, service, mock_repo):
+        mock_repo.find_by_id = AsyncMock(return_value={"id": "1", "name": "Test"})
+
+        result = await service.get_user("1")
+
+        assert result == {"id": "1", "name": "Test"}
+        mock_repo.find_by_id.assert_called_once_with("1")
+
+    async def test_get_user_raises_not_found(self, service, mock_repo):
+        mock_repo.find_by_id = AsyncMock(return_value=None)
+
+        with pytest.raises(NotFoundError):
+            await service.get_user("1")
+```
+
+## Mocking Patterns
+
+```typescript
+// Mock functions
+const mockFn = jest.fn();
+mockFn.mockReturnValue('value');
+mockFn.mockResolvedValue('async value');
+mockFn.mockRejectedValue(new Error('error'));
+
+// Mock modules
+jest.mock('./database', () => ({
+  query: jest.fn(),
+}));
+
+// Spy on existing methods
+jest.spyOn(console, 'log').mockImplementation(() => {});
+```
+
+## Test Organization
+
+```typescript
+describe('Feature', () => {
+  describe('happy path', () => {
+    it('does expected behavior', () => {});
+  });
+
+  describe('edge cases', () => {
+    it('handles empty input', () => {});
+    it('handles max values', () => {});
+  });
+
+  describe('error cases', () => {
+    it('throws on invalid input', () => {});
+  });
+});
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `describe()` | Group related tests |
+| `it()` / `test()` | Single test case |
+| `beforeEach()` | Setup before each test |
+| `jest.fn()` | Create mock function |
+| `mockResolvedValue()` | Mock async return |
+| `expect().toThrow()` | Assert exception |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/testing-patterns/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: testing-patterns
+description: "Compatibility alias skill. Deprecated: use test-master."
+metadata:
+  deprecated: true
+  replaced_by: test-master
+  removal_target: v0.6.0
+---
+
+# Testing Patterns
+
+## Compatibility Alias
+
+This skill is deprecated and kept for backward compatibility.
+
+Use `test-master` as the canonical skill.
+
+## Migration
+
+1. Replace direct references to `testing-patterns` with `test-master`.
+2. Apply the full workflow from `test-master` for new work.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/testing-patterns/scripts/test_runner.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+Test Runner - Unified test execution and coverage reporting
+Runs tests and generates coverage report based on project type.
+
+Usage:
+    python test_runner.py <project_path> [--coverage]
+
+Supports:
+    - Node.js: npm test, jest, vitest
+    - Python: pytest, unittest
+"""
+
+import subprocess
+import sys
+import json
+from pathlib import Path
+from datetime import datetime
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+except:
+    pass
+
+
+def detect_test_framework(project_path: Path) -> dict:
+    """Detect test framework and commands."""
+    result = {
+        "type": "unknown",
+        "framework": None,
+        "cmd": None,
+        "coverage_cmd": None
+    }
+    
+    # Node.js project
+    package_json = project_path / "package.json"
+    if package_json.exists():
+        result["type"] = "node"
+        try:
+            pkg = json.loads(package_json.read_text(encoding='utf-8'))
+            scripts = pkg.get("scripts", {})
+            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            
+            # Check for test script
+            if "test" in scripts:
+                result["framework"] = "npm test"
+                result["cmd"] = ["npm", "test"]
+                
+                # Try to detect specific framework for coverage
+                if "vitest" in deps:
+                    result["framework"] = "vitest"
+                    result["coverage_cmd"] = ["npx", "vitest", "run", "--coverage"]
+                elif "jest" in deps:
+                    result["framework"] = "jest"
+                    result["coverage_cmd"] = ["npx", "jest", "--coverage"]
+            elif "vitest" in deps:
+                result["framework"] = "vitest"
+                result["cmd"] = ["npx", "vitest", "run"]
+                result["coverage_cmd"] = ["npx", "vitest", "run", "--coverage"]
+            elif "jest" in deps:
+                result["framework"] = "jest"
+                result["cmd"] = ["npx", "jest"]
+                result["coverage_cmd"] = ["npx", "jest", "--coverage"]
+                
+        except:
+            pass
+    
+    # Python project
+    if (project_path / "pyproject.toml").exists() or (project_path / "requirements.txt").exists():
+        result["type"] = "python"
+        result["framework"] = "pytest"
+        result["cmd"] = ["python", "-m", "pytest", "-v"]
+        result["coverage_cmd"] = ["python", "-m", "pytest", "--cov", "--cov-report=term-missing"]
+    
+    return result
+
+
+def run_tests(cmd: list, cwd: Path) -> dict:
+    """Run tests and return results."""
+    result = {
+        "passed": False,
+        "output": "",
+        "error": "",
+        "tests_run": 0,
+        "tests_passed": 0,
+        "tests_failed": 0
+    }
+    
+    try:
+        proc = subprocess.run(
+            cmd,
+            cwd=str(cwd),
+            capture_output=True,
+            text=True,
+            encoding='utf-8',
+            errors='replace',
+            timeout=300  # 5 min timeout for tests
+        )
+        
+        result["output"] = proc.stdout[:3000] if proc.stdout else ""
+        result["error"] = proc.stderr[:500] if proc.stderr else ""
+        result["passed"] = proc.returncode == 0
+        
+        # Try to parse test counts from output
+        output = proc.stdout or ""
+        
+        # Jest/Vitest pattern: "Tests: X passed, Y failed, Z total"
+        if "passed" in output.lower() and "failed" in output.lower():
+            import re
+            match = re.search(r'(\d+)\s+passed', output, re.IGNORECASE)
+            if match:
+                result["tests_passed"] = int(match.group(1))
+            match = re.search(r'(\d+)\s+failed', output, re.IGNORECASE)
+            if match:
+                result["tests_failed"] = int(match.group(1))
+            result["tests_run"] = result["tests_passed"] + result["tests_failed"]
+        
+        # Pytest pattern: "X passed, Y failed"
+        if "pytest" in str(cmd):
+            import re
+            match = re.search(r'(\d+)\s+passed', output)
+            if match:
+                result["tests_passed"] = int(match.group(1))
+            match = re.search(r'(\d+)\s+failed', output)
+            if match:
+                result["tests_failed"] = int(match.group(1))
+            result["tests_run"] = result["tests_passed"] + result["tests_failed"]
+        
+    except FileNotFoundError:
+        result["error"] = f"Command not found: {cmd[0]}"
+    except subprocess.TimeoutExpired:
+        result["error"] = "Timeout after 300s"
+    except Exception as e:
+        result["error"] = str(e)
+    
+    return result
+
+
+def main():
+    project_path = Path(sys.argv[1] if len(sys.argv) > 1 else ".").resolve()
+    with_coverage = "--coverage" in sys.argv
+    
+    print(f"\n{'='*60}")
+    print(f"[TEST RUNNER] Unified Test Execution")
+    print(f"{'='*60}")
+    print(f"Project: {project_path}")
+    print(f"Coverage: {'enabled' if with_coverage else 'disabled'}")
+    print(f"Time: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+    
+    # Detect test framework
+    test_info = detect_test_framework(project_path)
+    print(f"Type: {test_info['type']}")
+    print(f"Framework: {test_info['framework']}")
+    print("-"*60)
+    
+    if not test_info["cmd"]:
+        print("No test framework found for this project.")
+        output = {
+            "script": "test_runner",
+            "project": str(project_path),
+            "type": test_info["type"],
+            "framework": None,
+            "passed": True,
+            "message": "No tests configured"
+        }
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    # Choose command
+    cmd = test_info["coverage_cmd"] if with_coverage and test_info["coverage_cmd"] else test_info["cmd"]
+    
+    print(f"Running: {' '.join(cmd)}")
+    print("-"*60)
+    
+    # Run tests
+    result = run_tests(cmd, project_path)
+    
+    # Print output (truncated)
+    if result["output"]:
+        lines = result["output"].split("\n")
+        for line in lines[:30]:
+            print(line)
+        if len(lines) > 30:
+            print(f"... ({len(lines) - 30} more lines)")
+    
+    # Summary
+    print("\n" + "="*60)
+    print("SUMMARY")
+    print("="*60)
+    
+    if result["passed"]:
+        print("[PASS] All tests passed")
+    else:
+        print("[FAIL] Some tests failed")
+        if result["error"]:
+            print(f"Error: {result['error'][:200]}")
+    
+    if result["tests_run"] > 0:
+        print(f"Tests: {result['tests_run']} total, {result['tests_passed']} passed, {result['tests_failed']} failed")
+    
+    output = {
+        "script": "test_runner",
+        "project": str(project_path),
+        "type": test_info["type"],
+        "framework": test_info["framework"],
+        "tests_run": result["tests_run"],
+        "tests_passed": result["tests_passed"],
+        "tests_failed": result["tests_failed"],
+        "passed": result["passed"]
+    }
+    
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if result["passed"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/typescript-pro/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: "typescript-pro"
+description: "Use for TypeScript architecture and implementation with TS 5.9+ production baselines and TS 6/7 transition readiness."
+license: MIT
+metadata:
+  version: "2.0.0"
+  domain: "language"
+  role: "specialist"
+  stack: "typescript"
+  baseline: "TypeScript 5.9 stable"
+  transition: "TypeScript 6 compatibility prep"
+---
+
+# TypeScript Pro
+
+## When to use
+
+- Designing type-safe APIs and shared contracts.
+- Refactoring codebases to strict TypeScript.
+- Reducing type regressions in monorepos.
+- Preparing for upcoming TS 6/7 behavior shifts.
+
+## When not to use
+
+- Plain JavaScript-only work where runtime constraints matter more than type architecture.
+- Database-only tuning with no TypeScript code change.
+- Simple shell or config edits that do not benefit from TS guidance.
+
+## Core workflow
+
+1. Confirm runtime and module target (Node, browser, edge).
+2. Lock strict compiler baseline before feature work.
+3. Model domain types first, then implement behavior.
+4. Keep runtime validation where untrusted input enters.
+5. Run type checks and targeted tests before finishing.
+
+## Baseline standards
+
+- Use `strict: true` and avoid opt-outs unless documented.
+- Prefer `unknown` over `any` at boundaries.
+- Use `satisfies` and `as const` for safer inference.
+- Keep public API types stable and explicit.
+- Use project references for large repos.
+
+## Implementation guidance
+
+- Encode state with discriminated unions.
+- Narrow with type guards instead of assertions.
+- Keep utility types readable; avoid type-level obfuscation.
+- Use schema validation (zod/valibot/etc.) for external input.
+- Treat type errors as design feedback, not noise.
+
+## Debugging and observability
+
+- Reproduce type regressions with focused compiler output before widening changes.
+- Keep runtime validation and structured logging at untrusted boundaries.
+- Prefer targeted failing examples over broad `as`-based workarounds.
+
+## Performance and reliability
+
+- Keep module boundaries explicit so public types stay stable.
+- Use incremental builds/project references deliberately in large repos.
+- Measure hot runtime paths separately from type-system complexity.
+
+## Avoid
+
+- Library-facing `any`.
+- Broad `as` casts to silence errors.
+- Hidden implicit `any` from weak tsconfig defaults.
+- Mixing runtime and type-only imports carelessly.
+
+## Reference files
+
+| File | Load when |
+| --- | --- |
+| `references/configuration.md` | `tsconfig`, strictness, module targets, or project references need detail. |
+| `references/advanced-types.md` | Generics, conditional types, mapped types, or template literals are central. |
+| `references/type-guards.md` | Narrowing and runtime-safe type refinement need detail. |
+| `references/utility-types.md` | Utility-type composition or shared helper types are in scope. |
+| `references/patterns.md` | Type-safe architecture patterns or public API design needs detail. |