timsquad 2.1.0 → 3.4.0

package/templates/base/skills/security/rules/owasp-examples.md

@@ -0,0 +1,119 @@
+---
+title: OWASP Top 10 Security Patterns
+impact: CRITICAL
+tags: security, owasp, vulnerability
+---
+
+# OWASP Top 10 — 코드 예시
+
+## 1. Injection
+```typescript
+// Bad
+const query = `SELECT * FROM users WHERE email = '${email}'`;
+
+// Good: Parameterized Query
+const query = 'SELECT * FROM users WHERE email = $1';
+await db.query(query, [email]);
+// Good: ORM 사용
+await userRepository.findOne({ where: { email } });
+```
+
+## 2. Broken Authentication
+```typescript
+// Bad
+if (password.length >= 4) { ... }
+
+// Good
+const passwordPolicy = {
+  minLength: 12, requireUppercase: true, requireLowercase: true,
+  requireNumber: true, requireSpecialChar: true,
+};
+const hash = await bcrypt.hash(password, 12);
+```
+
+## 3. Sensitive Data Exposure
+```typescript
+// Bad
+logger.info('User login', { email, password });
+return { ...user }; // passwordHash 포함
+
+// Good
+logger.info('User login', { email, password: '***' });
+return userToDto(user); // passwordHash 제외
+```
+
+## 5. Broken Access Control
+```typescript
+// Bad
+app.get('/api/users/:id', async (req, res) => {
+  const user = await userService.getUser(req.params.id);
+  return res.json(user);
+});
+
+// Good
+app.get('/api/users/:id', authenticate, authorize('user:read'), async (req, res) => {
+  if (req.user.id !== req.params.id && !req.user.isAdmin) throw new ForbiddenError();
+  const user = await userService.getUser(req.params.id);
+  return res.json(user);
+});
+```
+
+## 6. Security Misconfiguration
+```typescript
+app.use(helmet());
+app.use(helmet.contentSecurityPolicy({
+  directives: { defaultSrc: ["'self'"], scriptSrc: ["'self'"] },
+}));
+app.use(cors({ origin: ['https://allowed-domain.com'], credentials: true }));
+```
+
+## 7. XSS
+```typescript
+// Bad
+element.innerHTML = userInput;
+// Good
+element.textContent = userInput;
+```
+
+## 8. Insecure Deserialization
+```typescript
+// Bad
+const data = JSON.parse(userInput);
+// Good
+const schema = z.object({ name: z.string().max(100), age: z.number().min(0) });
+const data = schema.parse(JSON.parse(userInput));
+```
+
+## 9. Known Vulnerabilities
+```bash
+npm audit && npm audit fix
+npm outdated && npm update
+```
+
+## 10. Insufficient Logging
+```typescript
+logger.warn('Login failed', { email, ip: req.ip, timestamp: new Date().toISOString() });
+if (failedAttempts >= 5) {
+  logger.error('Possible brute force attack', { email, ip: req.ip });
+  await lockAccount(email);
+}
+```
+
+## Additional Checks
+
+### Rate Limiting
+```typescript
+import rateLimit from 'express-rate-limit';
+app.use('/api/', rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+```
+
+### CSRF 방지
+```typescript
+import csrf from 'csurf';
+app.use(csrf({ cookie: true }));
+```
+
+### 시크릿 관리
+- **금지**: `const apiKey = 'sk-1234567890';`
+- **필수**: `const apiKey = process.env.API_KEY;`
+- **권장**: `await secretManager.getSecret('api-key');`

package/templates/base/skills/security/scripts/check-secrets.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# @name check-secrets
+# @description 하드코딩된 시크릿/토큰/비밀번호를 소스코드에서 스캔
+# @args [PROJECT_ROOT] (기본: 현재 디렉토리)
+# @output text (발견된 파일:라인 목록 또는 "No secrets found")
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-.}"
+FOUND=0
+
+echo "Scanning for hardcoded secrets in: $PROJECT_ROOT"
+echo "================================================"
+
+# Pattern 1: API keys, tokens, secrets in assignments
+echo ""
+echo "## Hardcoded API Keys / Tokens"
+if grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.go" \
+  -E "(api_key|apiKey|API_KEY|secret|SECRET|token|TOKEN|password|PASSWORD)\s*[:=]\s*['\"][^'\"]{8,}" \
+  "$PROJECT_ROOT/src" "$PROJECT_ROOT/app" "$PROJECT_ROOT/lib" 2>/dev/null | \
+  grep -v "node_modules" | grep -v ".test." | grep -v "__mock__" | grep -v "example" | grep -v "placeholder"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+# Pattern 2: .env files committed
+echo ""
+echo "## Committed .env Files"
+if find "$PROJECT_ROOT" -name ".env" -o -name ".env.local" -o -name ".env.production" 2>/dev/null | \
+  grep -v "node_modules" | grep -v ".example"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+# Pattern 3: Private keys
+echo ""
+echo "## Private Keys"
+if grep -rn --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.pem" --include="*.key" \
+  -l "PRIVATE KEY" "$PROJECT_ROOT" 2>/dev/null | grep -v "node_modules"; then
+  FOUND=1
+else
+  echo "  (none found)"
+fi
+
+echo ""
+echo "================================================"
+if [ "$FOUND" -eq 1 ]; then
+  echo "WARNING: Potential secrets found. Review above results."
+  exit 1
+else
+  echo "No secrets found."
+  exit 0
+fi

package/templates/base/skills/testing/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: testing
+description: |
+  테스트 작성 규칙 및 패턴 가이드라인.
+  TDD 사이클, 테스트 피라미드, Given-When-Then 패턴, 커버리지 기준을 다룸.
+  Use when: "테스트 작성, TDD, 단위 테스트, 통합 테스트, E2E, 커버리지"
+version: "1.0.0"
+tags: [testing, tdd, quality]
+user-invocable: false
+---
+
+# Testing
+
+품질 보장을 위한 테스트 작성 가이드라인.
+
+## Philosophy
+
+- Red-Green-Refactor (TDD 사이클) 준수
+- 테스트 피라미드: Unit(다수) > Integration(중간) > E2E(소수)
+- 행동(behavior) 테스트 — 구현 디테일이 아닌 결과 검증
+
+## Resources
+
+| Priority | Type | Resource | Description |
+|----------|------|----------|-------------|
+| HIGH | ref | [testing-patterns](references/testing-patterns.md) | Given-When-Then, Mock 가이드, 카테고리별 예시 |
+
+## Quick Rules
+
+### TDD Cycle
+1. **Red** — 실패하는 테스트 작성
+2. **Green** — 테스트를 통과하는 최소 코드 작성
+3. **Refactor** — 코드 정리 (테스트는 계속 통과)
+
+### Test Naming
+- 형식: `should {expected behavior} when {condition}`
+- Good: `should return null when user is not found`
+- Bad: `test getUser`, `works correctly`
+
+### Test Categories
+모든 테스트는 3가지 카테고리 커버:
+- **Happy Path** — 정상 흐름
+- **Edge Cases** — 경계 조건 (빈 문자열, 0, null, 최대값)
+- **Error Cases** — 오류 상황
+
+### Coverage Standards
+
+| Metric | Minimum | Recommended |
+|--------|---------|-------------|
+| Line Coverage | 80% | 90% |
+| Branch Coverage | 70% | 80% |
+| Function Coverage | 80% | 90% |
+
+## Checklist
+
+| Priority | Item |
+|----------|------|
+| CRITICAL | Given-When-Then 패턴을 따르는가 |
+| CRITICAL | Happy path, Edge case, Error case 커버하는가 |
+| HIGH | 테스트 이름이 `should...when...` 형식인가 |
+| HIGH | 커버리지 기준을 충족하는가 |
+| MEDIUM | Mock이 적절히 사용되었는가 (외부 서비스만) |
+| MEDIUM | 테스트가 독립적인가 (순서 무관) |

package/templates/base/skills/testing/references/testing-patterns.md

@@ -0,0 +1,103 @@
+---
+title: Testing Patterns & Examples
+category: guide
+source: internal
+---
+
+# Testing Patterns & Examples
+
+Given-When-Then 패턴, 테스트 카테고리별 예시, Mock 가이드라인을 다루는 심층 가이드.
+
+## Given-When-Then Pattern
+
+```typescript
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create a new user when email is unique', async () => {
+      // Given: 테스트 조건 설정
+      const userRepository = createMockRepository();
+      userRepository.findByEmail.mockResolvedValue(null);
+      const service = new UserService(userRepository);
+
+      // When: 테스트 대상 실행
+      const result = await service.createUser({
+        email: 'test@example.com',
+        password: 'password123',
+      });
+
+      // Then: 결과 검증
+      expect(result.email).toBe('test@example.com');
+      expect(userRepository.save).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error when email already exists', async () => {
+      // Given
+      const userRepository = createMockRepository();
+      userRepository.findByEmail.mockResolvedValue({ id: '1', email: 'test@example.com' });
+      const service = new UserService(userRepository);
+
+      // When & Then
+      await expect(
+        service.createUser({ email: 'test@example.com', password: 'password123' })
+      ).rejects.toThrow('EMAIL_ALREADY_EXISTS');
+    });
+  });
+});
+```
+
+## Test Categories
+
+### Happy Path
+정상적인 흐름 테스트.
+
+```typescript
+it('should return user when valid id is provided', async () => {
+  const user = await userService.getUser('valid-id');
+  expect(user).toBeDefined();
+  expect(user.id).toBe('valid-id');
+});
+```
+
+### Edge Cases
+경계 조건: 빈 문자열, 최대 길이 입력, 0 값, null 입력.
+
+### Error Cases
+오류 상황 테스트.
+
+```typescript
+it('should throw NotFoundError when user does not exist', async () => {
+  await expect(userService.getUser('non-existent-id'))
+    .rejects
+    .toThrow(NotFoundError);
+});
+```
+
+## Mock Guidelines
+
+### When to Mock
+- 외부 서비스 (DB, API, 파일시스템)
+- 비결정적 요소 (시간, 랜덤)
+- 느린 작업
+
+### Mock Examples
+
+```typescript
+// Repository Mock
+const mockUserRepository: jest.Mocked<UserRepository> = {
+  findById: jest.fn(),
+  findByEmail: jest.fn(),
+  save: jest.fn(),
+  delete: jest.fn(),
+};
+
+// 시간 Mock
+jest.useFakeTimers();
+jest.setSystemTime(new Date('2024-01-01'));
+```
+
+## Common Pitfalls
+
+- Mock을 과도하게 사용하면 실제 동작과 괴리 발생
+- 테스트 간 상태 공유 → `beforeEach`에서 초기화 필수
+- 구현 디테일을 테스트하면 리팩토링 시 깨짐 → 행동(behavior) 테스트
+- `any` 타입 mock은 타입 안전성 무력화 → 타입 지정 mock 사용

package/templates/base/skills/tsq-protocol/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: tsq-protocol
+description: |
+  TimSquad 에이전트 공통 프로토콜.
+  task-context.json 우선 탐색, TSQ CLI 사용, 로그/피드백 규칙.
+  자동 주입 스킬 — 직접 호출하지 마세요.
+version: "1.0.0"
+tags: [tsq, protocol, agent]
+user-invocable: false
+---
+
+# TSQ Agent Protocol
+
+## File Access
+코드 탐색 시 `.timsquad/.daemon/task-context.json`을 **먼저** 확인하세요.
+이 파일에 작업 범위의 파일/메서드/클래스 위치가 정리되어 있습니다.
+context 파일이 없거나 범위 밖 파일이 필요할 때만 Grep/Glob을 사용하세요.
+
+## TSQ CLI (Required)
+
+모든 로그/피드백/커밋은 TSQ CLI를 통해서만 수행합니다. 직접 파일 조작 금지.
+
+| 이벤트 | 커맨드 |
+|--------|--------|
+| 작업 시작 | `tsq log add {agent} work "TASK-XXX 시작: {설명}"` |
+| 결정 기록 | `tsq log add {agent} decision "{결정 근거}"` |
+| 이슈 발견 | `tsq feedback "{이슈 설명}"` |
+| 작업 완료 | `tsq log add {agent} work "TASK-XXX 완료: {결과}"` |
+| semantic 보강 | `tsq log enrich {agent} --json '{...}'` |
+| 커밋 | `tsq commit -m "{메시지}"` (developer/dba만) |
+
+### Forbidden
+- 직접 `.timsquad/logs/` 파일 생성/수정 금지 → `tsq log` 사용
+- 직접 `.timsquad/feedback/` 파일 생성 금지 → `tsq feedback` 사용
+- 직접 `git commit` 금지 → `tsq commit` 사용 (해당 역할만)
+
+## Output Format
+작업 결과는 `knowledge/templates/task-result.md` 형식으로 리턴하세요.
+
+## Feedback Routing
+
+| Level | 심각도 | 기준 | 라우팅 |
+|-------|--------|------|--------|
+| L1 | Minor | 즉시 수정 가능 (린트, 타입, 스타일) | 자체 수정 또는 @tsq-developer |
+| L2 | Major | 설계 변경 필요 (API 불일치, 성능 구조) | 메인세션(PM) 보고 |
+| L3 | Critical | 요구사항 오류, 스코프 변경, 데이터 손실 위험 | 메인세션(PM) → 사용자 승인 |
+
+모든 피드백에 Level 분류와 심각도를 반드시 명시하세요.
+
+## Mandatory Skills
+작업 시작 전 에이전트 frontmatter에 지정된 스킬 파일을 반드시 읽고 가이드라인을 준수하세요.

package/templates/base/skills/typescript/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: typescript
+description: TypeScript 개발 가이드라인
+version: "1.0.0"
+tags: [typescript, types, strict]
+user-invocable: false
+---
+
+# TypeScript Guidelines
+
+## 철학
+- 타입은 문서다 — 코드만 봐도 의도 파악
+- 컴파일 타임에 버그를 잡는다
+- any는 타입 시스템 포기 선언
+
+## 필수 설정 (tsconfig.json)
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+## 핵심 패턴 (상세: `rules/type-patterns.md`)
+
+| 패턴 | 용도 |
+|------|------|
+| Discriminated Union | 상태 표현 (불가능한 상태를 불가능하게) |
+| Type Narrowing | typeof, in, type guard로 안전한 접근 |
+| Branded Types | 같은 원시 타입이지만 의미 구분 (UserId vs OrderId) |
+| Template Literal Types | 문자열 패턴 타입 강제 |
+| Infer | 조건부 타입에서 타입 추출 |
+| Zod | 외부 입력 런타임 검증 + 타입 추출 |
+
+## Rules
+
+### 필수
+- strict 모드 사용
+- 함수 반환 타입 명시
+- 외부 입력(API, 사용자)은 Zod로 런타임 검증
+- Discriminated Union으로 상태 표현
+- Branded Types로 ID 타입 구분
+
+### 금지
+- `any` 사용 → `unknown` + type guard
+- 타입 단언 남용 (`as Type`)
+- `@ts-ignore`, `@ts-expect-error` 남용
+- `!` non-null assertion 남용
+
+## Checklist
+- [ ] strict 모드 활성화
+- [ ] any 타입 없음
+- [ ] 함수 반환 타입 명시
+- [ ] 외부 입력 Zod 검증
+- [ ] Discriminated Union으로 상태 표현
+- [ ] Branded Types로 ID 구분
+
+## 참조
+- `rules/type-patterns.md` — 각 패턴의 코드 예시
+- `rules/utility-types.md` — DTO 조합, DeepPartial, 타입 안전 API 클라이언트

package/templates/base/skills/typescript/rules/type-patterns.md

@@ -0,0 +1,135 @@
+---
+title: TypeScript Type Patterns
+impact: HIGH
+tags: typescript, types, patterns
+---
+
+# TypeScript Type Patterns
+
+## Discriminated Union (상태 표현의 정석)
+status 필드로 타입을 구분하여 불가능한 상태를 불가능하게.
+
+```typescript
+// Bad: 불가능한 상태가 가능함
+interface ApiResponse { data?: User; error?: string; loading: boolean; }
+
+// Good: 불가능한 상태는 타입으로 불가능
+type ApiResponse<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+
+function renderUser(state: ApiResponse<User>) {
+  switch (state.status) {
+    case 'idle': return null;
+    case 'loading': return <Spinner />;
+    case 'success': return <UserCard user={state.data} />;
+    case 'error': return <ErrorMessage error={state.error} />;
+  }
+}
+```
+
+## Type Narrowing (타입 좁히기)
+
+```typescript
+// typeof narrowing
+function process(value: string | number) {
+  if (typeof value === 'string') return value.toUpperCase();
+  return value.toFixed(2);
+}
+
+// in narrowing
+function move(animal: Fish | Bird) {
+  if ('swim' in animal) animal.swim();
+  else animal.fly();
+}
+
+// Custom Type Guard
+function isError(value: unknown): value is Error {
+  return value instanceof Error;
+}
+
+// Assertion Function
+function assertDefined<T>(value: T | null | undefined): asserts value is T {
+  if (value === null || value === undefined) throw new Error('Value is not defined');
+}
+```
+
+## Branded Types (타입 브랜딩)
+같은 원시 타입이지만 의미가 다른 값을 구분.
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+type OrderId = string & { readonly __brand: 'OrderId' };
+
+function createUserId(id: string): UserId {
+  if (!id.startsWith('user-')) throw new Error('Invalid user ID format');
+  return id as UserId;
+}
+
+function getUser(id: UserId): Promise<User> { ... }
+function getOrder(id: OrderId): Promise<Order> { ... }
+
+getUser(userId);   // ✅ OK
+getUser(orderId);  // ❌ Type Error!
+
+// 응용
+type Money = number & { readonly __brand: 'Money' };
+type Email = string & { readonly __brand: 'Email' };
+```
+
+## Template Literal Types
+
+```typescript
+type ApiPath = `/api/${string}`;
+fetchApi('/api/users');  // ✅
+fetchApi('/users');      // ❌
+
+type CSSUnit = `${number}${'px' | 'rem' | 'em' | '%'}`;
+const width: CSSUnit = '100px';  // ✅
+```
+
+## Infer로 타입 추출
+
+```typescript
+type Awaited<T> = T extends Promise<infer U> ? U : T;
+type ArrayElement<T> = T extends (infer U)[] ? U : never;
+type FirstArg<T> = T extends (first: infer F, ...args: any[]) => any ? F : never;
+
+// API 응답에서 data 타입 추출
+type ApiResponse<T> = { success: true; data: T } | { success: false; error: string };
+type ExtractData<T> = T extends { success: true; data: infer D } ? D : never;
+```
+
+## Zod 런타임 검증
+외부 입력은 타입만으로 부족, 런타임 검증 필요.
+
+```typescript
+import { z } from 'zod';
+
+const userSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  name: z.string().min(2).max(50),
+  role: z.enum(['admin', 'user', 'guest']),
+});
+
+type User = z.infer<typeof userSchema>;
+
+// API 핸들러
+async function createUser(req: Request) {
+  const result = userSchema.safeParse(req.body);
+  if (!result.success) return { error: result.error.format() };
+  const user = result.data;
+  await db.user.create({ data: user });
+}
+
+// 환경변수 검증
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  PORT: z.coerce.number().default(3000),
+});
+export const env = envSchema.parse(process.env);
+```

package/templates/base/skills/typescript/rules/utility-types.md

@@ -0,0 +1,76 @@
+---
+title: TypeScript Utility Types & Advanced Patterns
+impact: HIGH
+tags: typescript, utility-types, advanced
+---
+
+# TypeScript Utility Types & Advanced Patterns
+
+## DTO 타입 조합
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+  name: string;
+  password: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+type CreateUserDto = Omit<User, 'id' | 'createdAt' | 'updatedAt'>;
+type UpdateUserDto = Partial<Omit<User, 'id' | 'createdAt' | 'updatedAt'>>;
+type UserResponseDto = Omit<User, 'password'>;
+
+type UsersListDto = {
+  users: UserResponseDto[];
+  total: number;
+  page: number;
+  limit: number;
+};
+```
+
+## DeepPartial / DeepReadonly
+
+```typescript
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+type DeepReadonly<T> = {
+  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+```
+
+## 타입 안전한 API 클라이언트
+
+```typescript
+type ApiEndpoint = {
+  '/users': {
+    GET: { response: User[]; query?: { page?: number; limit?: number } };
+    POST: { response: User; body: CreateUserDto };
+  };
+  '/users/:id': {
+    GET: { response: User; params: { id: string } };
+    PUT: { response: User; params: { id: string }; body: UpdateUserDto };
+    DELETE: { response: void; params: { id: string } };
+  };
+};
+
+async function api<
+  Path extends keyof ApiEndpoint,
+  Method extends keyof ApiEndpoint[Path]
+>(
+  path: Path,
+  method: Method,
+  options?: ApiEndpoint[Path][Method] extends { body: infer B } ? { body: B } : never
+): Promise<ApiEndpoint[Path][Method] extends { response: infer R } ? R : never> {
+  // 구현
+}
+
+const users = await api('/users', 'GET');       // User[]
+const user = await api('/users', 'POST', {
+  body: { email: 'a@b.com', name: 'Test', password: '...' }
+}); // User
+await api('/users', 'DELETE'); // ❌ DELETE는 /users에 없음
+```