agentic-team-templates 0.13.2 → 0.15.0

package/templates/javascript-expert/.cursorrules/typescript-deep-dive.md

@@ -0,0 +1,348 @@
+# TypeScript Deep Dive
+
+Advanced type system mastery. Conditional types, mapped types, type-level programming, and runtime boundary validation.
+
+This builds on the type safety foundations in overview.md. That file covers discriminated unions, branded types, and const assertions. This file goes deeper.
+
+## Generics — Beyond the Basics
+
+```typescript
+// Constrained generics
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Generic with defaults
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+// Multiple constraints
+function merge<T extends object, U extends object>(a: T, b: U): T & U {
+  return { ...a, ...b };
+}
+
+// Generic factory functions
+function createStore<T>(initial: T) {
+  let state = initial;
+  return {
+    get: (): T => state,
+    set: (next: T): void => { state = next; },
+    update: (fn: (current: T) => T): void => { state = fn(state); },
+  };
+}
+// Type is inferred from usage — no annotation needed at call site
+const counter = createStore(0); // Store<number>
+const users = createStore<User[]>([]); // Explicit when needed
+```
+
+## Conditional Types
+
+```typescript
+// Basic conditional
+type IsString<T> = T extends string ? true : false;
+
+// Extract and Exclude (built-in, but understand how they work)
+type Extract<T, U> = T extends U ? T : never;
+type Exclude<T, U> = T extends U ? never : T;
+
+// Practical: extract function return types from a module
+type ApiMethods = {
+  getUser: (id: string) => Promise<User>;
+  createUser: (data: CreateUserInput) => Promise<User>;
+  deleteUser: (id: string) => Promise<void>;
+};
+
+type ApiReturnTypes = {
+  [K in keyof ApiMethods]: ApiMethods[K] extends (...args: any[]) => infer R ? R : never;
+};
+// { getUser: Promise<User>; createUser: Promise<User>; deleteUser: Promise<void> }
+
+// Unwrap Promise
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+type UserResult = Awaited<Promise<Promise<User>>>; // User
+
+// Distributive conditional types — union members are distributed
+type ToArray<T> = T extends unknown ? T[] : never;
+type Result = ToArray<string | number>; // string[] | number[]
+
+// Prevent distribution with tuple wrapping
+type ToArrayNonDist<T> = [T] extends [unknown] ? T[] : never;
+type Result2 = ToArrayNonDist<string | number>; // (string | number)[]
+```
+
+## Mapped Types
+
+```typescript
+// Transform all properties
+type Readonly<T> = { readonly [K in keyof T]: T[K] };
+type Partial<T> = { [K in keyof T]?: T[K] };
+type Nullable<T> = { [K in keyof T]: T[K] | null };
+
+// Key remapping (TypeScript 4.1+)
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+type UserGetters = Getters<{ name: string; age: number }>;
+// { getName: () => string; getAge: () => number }
+
+// Filter keys by value type
+type PickByType<T, V> = {
+  [K in keyof T as T[K] extends V ? K : never]: T[K];
+};
+
+type StringFields = PickByType<User, string>;
+// Only string-typed fields from User
+
+// Deep mapped types
+type DeepReadonly<T> = {
+  readonly [K in keyof T]: T[K] extends object
+    ? T[K] extends Function
+      ? T[K]
+      : DeepReadonly<T[K]>
+    : T[K];
+};
+
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object
+    ? T[K] extends Function
+      ? T[K]
+      : DeepPartial<T[K]>
+    : T[K];
+};
+```
+
+## Template Literal Types
+
+```typescript
+// Type-safe string manipulation
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+type ApiPath = `/api/v1/${string}`;
+type Route = `${HttpMethod} ${ApiPath}`;
+
+// Extract route parameters
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<`/${Rest}`>
+    : T extends `${string}:${infer Param}`
+      ? Param
+      : never;
+
+type Params = ExtractParams<'/users/:userId/posts/:postId'>;
+// "userId" | "postId"
+
+// Type-safe event emitter
+type EventHandler<T extends string> = `on${Capitalize<T>}`;
+type ClickHandler = EventHandler<'click'>; // "onClick"
+
+// Dot-notation paths for nested objects
+type DotPath<T, Prefix extends string = ''> = T extends object
+  ? {
+      [K in keyof T & string]: T[K] extends object
+        ? `${Prefix}${K}` | DotPath<T[K], `${Prefix}${K}.`>
+        : `${Prefix}${K}`;
+    }[keyof T & string]
+  : never;
+
+type UserPaths = DotPath<{ name: string; address: { city: string; zip: string } }>;
+// "name" | "address" | "address.city" | "address.zip"
+```
+
+## Type Predicates and Assertion Functions
+
+```typescript
+// Type predicates — custom narrowing functions
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    typeof (value as Record<string, unknown>).id === 'string' &&
+    'email' in value &&
+    typeof (value as Record<string, unknown>).email === 'string'
+  );
+}
+
+// Works in filter — TypeScript narrows the array type
+const users: User[] = mixedArray.filter(isUser);
+
+// Assertion functions — throw or narrow
+function assertUser(value: unknown): asserts value is User {
+  if (!isUser(value)) {
+    throw new TypeError('Expected User');
+  }
+}
+
+// After calling assertUser, TypeScript knows value is User
+assertUser(data);
+data.email; // OK — narrowed to User
+
+// Type predicate for discriminated unions
+function isSuccess<T>(result: Result<T>): result is { ok: true; value: T } {
+  return result.ok;
+}
+```
+
+## satisfies Operator
+
+```typescript
+// Validate a type without widening — the best of both worlds
+const palette = {
+  red: [255, 0, 0],
+  green: '#00ff00',
+  blue: [0, 0, 255],
+} satisfies Record<string, string | readonly number[]>;
+
+// palette.red is number[] (not string | number[])
+// palette.green is string (not string | number[])
+// But TypeScript verified it matches Record<string, string | number[]>
+
+// Route config example
+const routes = {
+  home: { path: '/', component: HomePage },
+  about: { path: '/about', component: AboutPage },
+  user: { path: '/users/:id', component: UserPage },
+} satisfies Record<string, { path: string; component: React.ComponentType }>;
+
+// routes.home.path is the literal "/" — not widened to string
+```
+
+## Runtime Boundary Validation
+
+```typescript
+// Types disappear at runtime. Validate at every I/O boundary.
+import { z } from 'zod';
+
+// Schema is the single source of truth — infer the type from it
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(200),
+  email: z.string().email(),
+  role: z.enum(['admin', 'user', 'viewer']),
+  createdAt: z.string().datetime(),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+// Validate at boundaries
+async function handleCreateUser(req: Request): Promise<Response> {
+  const body = await req.json();
+  const parsed = UserSchema.safeParse(body);
+  if (!parsed.success) {
+    return Response.json(
+      { errors: parsed.error.flatten().fieldErrors },
+      { status: 400 },
+    );
+  }
+  // parsed.data is fully typed User
+  const user = await db.users.create(parsed.data);
+  return Response.json(user, { status: 201 });
+}
+
+// Validate environment variables at startup — fail fast
+const EnvSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  PORT: z.coerce.number().int().positive().default(3000),
+});
+export const env = EnvSchema.parse(process.env);
+
+// Validate external API responses — don't trust the network
+const ExternalUserSchema = z.object({
+  id: z.number(),
+  login: z.string(),
+  avatar_url: z.string().url(),
+});
+
+async function fetchGitHubUser(username: string) {
+  const response = await fetch(`https://api.github.com/users/${username}`);
+  const data = await response.json();
+  return ExternalUserSchema.parse(data); // Throws if shape is wrong
+}
+```
+
+## Declaration Files and Library Types
+
+```typescript
+// Augment third-party types
+declare module 'express' {
+  interface Request {
+    user?: AuthenticatedUser;
+    requestId: string;
+  }
+}
+
+// Augment global types
+declare global {
+  interface Window {
+    __APP_CONFIG__: AppConfig;
+  }
+}
+
+// Type-only imports (tree-shakeable, explicit intent)
+import type { User } from './types.js';
+
+// For library authors: ensure .d.ts files are generated
+// tsconfig.json: "declaration": true, "declarationMap": true
+// package.json: "types": "./dist/index.d.ts"
+```
+
+## Utility Patterns
+
+```typescript
+// Make specific keys required
+type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+type UserWithEmail = WithRequired<Partial<User>, 'email'>;
+
+// Make specific keys optional
+type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+type UpdateUser = WithOptional<User, 'id' | 'createdAt'>;
+
+// Strict extract for exhaustive checking
+type StrictExtract<T, U extends T> = Extract<T, U>;
+
+// Non-empty array type
+type NonEmptyArray<T> = [T, ...T[]];
+function first<T>(arr: NonEmptyArray<T>): T {
+  return arr[0]; // No undefined — guaranteed at least one element
+}
+
+// Exact types (prevent excess properties in specific contexts)
+type Exact<T, Shape> = T extends Shape
+  ? Exclude<keyof T, keyof Shape> extends never
+    ? T
+    : never
+  : never;
+```
+
+## Anti-Patterns
+
+```typescript
+// Never: any
+function process(data: any) { } // Type checker disabled entirely
+// Use: unknown, then narrow with type guards or Zod
+
+// Never: as for silencing errors
+const user = data as User; // What if data is garbage?
+// Use: runtime validation, then the type follows
+
+// Never: enums (they generate runtime code and have surprising behavior)
+enum Status { Active, Inactive } // 0, 1 — not "Active", "Inactive"
+// Use: string literal unions
+type Status = 'active' | 'inactive';
+
+// Never: non-null assertion (!) without proof
+user!.email; // Runtime NPE waiting to happen
+// Use: if (user) { user.email }
+
+// Never: @ts-ignore without explanation
+// @ts-ignore
+brokenCode();
+// Use: @ts-expect-error — explanation of why this is necessary
+// At minimum, @ts-expect-error will fail if the error is fixed (unlike @ts-ignore)
+
+// Never: interface for unions or mapped types (use type alias)
+// Interfaces are for object shapes that may be extended/implemented
+// Type aliases are for unions, intersections, mapped types, conditional types
+```

package/templates/javascript-expert/CLAUDE.md

@@ -1,6 +1,8 @@
-# JavaScript Expert Development Guide
+# JavaScript & TypeScript Expert Development Guide
 
-Comprehensive guidelines for principal-level JavaScript engineering across all runtimes, frameworks, and paradigms.
+Comprehensive guidelines for principal-level JavaScript and TypeScript engineering across all runtimes, frameworks, and paradigms.
+
+**This template covers both JavaScript and TypeScript.** TypeScript is the default — all code is written in strict TypeScript. Advanced type system patterns (conditional types, mapped types, generics, runtime validation) are included.
 
 ---
 
@@ -10,7 +12,7 @@ This guide applies to:
 - Node.js services, CLIs, and tooling
 - React, Vue, Angular, Svelte, and other UI frameworks
 - Vanilla JavaScript and Web APIs
-- TypeScript (strict mode, always)
+- TypeScript (strict mode, always) — including advanced type system patterns
 - Build tools, bundlers, and transpilers
 - Testing at every level (unit, integration, E2E, performance)
 
@@ -76,6 +78,35 @@ const EVENTS = ['click', 'keydown', 'submit'] as const;
 type EventName = (typeof EVENTS)[number];
 ```
 
+### TypeScript Deep Dive
+
+Advanced type system patterns beyond the basics:
+
+```typescript
+// Conditional types
+type Awaited<T> = T extends Promise<infer U> ? Awaited<U> : T;
+
+// Mapped types with key remapping
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+// Template literal type extraction
+type ExtractParams<T extends string> =
+  T extends `${string}:${infer Param}/${infer Rest}`
+    ? Param | ExtractParams<`/${Rest}`>
+    : T extends `${string}:${infer Param}` ? Param : never;
+
+// satisfies — validate without widening
+const config = { port: 3000, host: 'localhost' } satisfies Record<string, string | number>;
+// config.port is still number, not string | number
+
+// Runtime boundary validation with Zod
+const UserSchema = z.object({ id: z.string().uuid(), email: z.string().email() });
+type User = z.infer<typeof UserSchema>;
+// Types disappear at runtime — validate at every I/O boundary
+```
+
 ### Functional Patterns
 
 ```typescript

package/templates/kotlin-expert/.cursorrules/coroutines.md

@@ -0,0 +1,237 @@
+# Kotlin Coroutines
+
+Structured concurrency is the law. Every coroutine has a scope. Every scope has a lifecycle.
+
+## Fundamentals
+
+```kotlin
+// Coroutines are lightweight — thousands are cheap
+suspend fun fetchUser(id: UserId): User {
+    return userRepository.findById(id)
+        ?: throw NotFoundException("User", id.value)
+}
+
+// suspend functions can only be called from coroutines or other suspend functions
+// They mark suspension points — where the function may pause and resume
+```
+
+## Structured Concurrency
+
+```kotlin
+// Every coroutine lives in a scope — when the scope cancels, all children cancel
+class UserService(
+    private val userRepo: UserRepository,
+    private val emailService: EmailService,
+) {
+    // CoroutineScope tied to service lifecycle
+    suspend fun register(request: CreateUserRequest): User {
+        val user = userRepo.create(request)
+        // This child coroutine is tied to the caller's scope
+        emailService.sendWelcome(user.email)
+        return user
+    }
+}
+
+// Parallel decomposition with coroutineScope
+suspend fun loadDashboard(userId: UserId): Dashboard = coroutineScope {
+    val userDeferred = async { userService.findById(userId) }
+    val ordersDeferred = async { orderService.findRecent(userId) }
+    val statsDeferred = async { statsService.forUser(userId) }
+
+    Dashboard(
+        user = userDeferred.await(),
+        orders = ordersDeferred.await(),
+        stats = statsDeferred.await()
+    )
+}
+// If any async fails, ALL are cancelled — no orphaned work
+```
+
+## Dispatchers
+
+```kotlin
+// Dispatchers.IO — blocking I/O (database, file, network)
+withContext(Dispatchers.IO) {
+    database.query(sql)
+}
+
+// Dispatchers.Default — CPU-intensive computation
+withContext(Dispatchers.Default) {
+    data.map { expensiveTransform(it) }
+}
+
+// Dispatchers.Main — UI thread (Android)
+withContext(Dispatchers.Main) {
+    updateUI(result)
+}
+
+// Never create custom thread pools unless you have a specific reason
+// The built-in dispatchers are well-tuned
+```
+
+## Flow
+
+```kotlin
+// Cold asynchronous stream — values emitted on demand
+fun observeUsers(): Flow<List<User>> = flow {
+    while (true) {
+        emit(userRepository.findAll())
+        delay(5.seconds)
+    }
+}
+
+// Operators
+val activeUserNames: Flow<String> = observeUsers()
+    .map { users -> users.filter { it.isActive } }
+    .flatMapConcat { users -> users.asFlow() }
+    .map { it.name }
+    .distinctUntilChanged()
+
+// StateFlow — hot observable with current value (replaces LiveData)
+class UserViewModel : ViewModel() {
+    private val _state = MutableStateFlow<UiState>(UiState.Loading)
+    val state: StateFlow<UiState> = _state.asStateFlow()
+
+    fun loadUser(id: UserId) {
+        viewModelScope.launch {
+            _state.value = UiState.Loading
+            try {
+                val user = userService.findById(id)
+                _state.value = UiState.Success(user)
+            } catch (e: Exception) {
+                _state.value = UiState.Error(e.message ?: "Unknown error")
+            }
+        }
+    }
+}
+
+// SharedFlow — hot stream for events (no replay by default)
+class EventBus {
+    private val _events = MutableSharedFlow<AppEvent>()
+    val events: SharedFlow<AppEvent> = _events.asSharedFlow()
+
+    suspend fun emit(event: AppEvent) = _events.emit(event)
+}
+
+// Collecting flows
+lifecycleScope.launch {
+    viewModel.state.collect { state ->
+        when (state) {
+            is UiState.Loading -> showLoading()
+            is UiState.Success -> showUser(state.user)
+            is UiState.Error -> showError(state.message)
+        }
+    }
+}
+```
+
+## Cancellation
+
+```kotlin
+// Cooperative cancellation — coroutines must check for cancellation
+suspend fun processItems(items: List<Item>) {
+    for (item in items) {
+        ensureActive() // Throws CancellationException if cancelled
+        process(item)
+    }
+}
+
+// All suspend functions in kotlinx.coroutines are cancellable
+// delay(), yield(), withContext(), etc. check for cancellation
+
+// CancellationException is special — it doesn't propagate as failure
+// Use it for normal cancellation, not for errors
+
+// Timeout
+val result = withTimeout(5.seconds) {
+    fetchDataFromNetwork()
+}
+
+// Timeout with null instead of exception
+val result = withTimeoutOrNull(5.seconds) {
+    fetchDataFromNetwork()
+}
+```
+
+## Exception Handling
+
+```kotlin
+// CoroutineExceptionHandler — last resort for uncaught exceptions
+val handler = CoroutineExceptionHandler { _, exception ->
+    logger.error("Uncaught coroutine exception", exception)
+}
+
+// supervisorScope — child failure doesn't cancel siblings
+suspend fun fetchAllData(): DashboardData = supervisorScope {
+    val user = async { fetchUser() }
+    val orders = async { fetchOrders() }     // If this fails...
+    val stats = async { fetchStats() }       // ...this continues
+
+    DashboardData(
+        user = user.await(),
+        orders = runCatching { orders.await() }.getOrDefault(emptyList()),
+        stats = runCatching { stats.await() }.getOrNull()
+    )
+}
+
+// try-catch in coroutines
+launch {
+    try {
+        riskyOperation()
+    } catch (e: Exception) {
+        if (e is CancellationException) throw e // Never catch cancellation
+        logger.error("Operation failed", e)
+    }
+}
+```
+
+## Channels
+
+```kotlin
+// Producer-consumer with bounded channel
+val channel = Channel<Event>(capacity = Channel.BUFFERED)
+
+// Producer
+launch {
+    for (event in events) {
+        channel.send(event) // Suspends if buffer is full
+    }
+    channel.close()
+}
+
+// Consumer
+launch {
+    for (event in channel) { // Iterates until channel is closed
+        process(event)
+    }
+}
+
+// Fan-out: multiple consumers from one channel
+repeat(workerCount) {
+    launch { for (event in channel) process(event) }
+}
+```
+
+## Anti-Patterns
+
+```kotlin
+// Never: GlobalScope
+GlobalScope.launch { } // No lifecycle, no cancellation, leaks coroutines
+// Use: viewModelScope, lifecycleScope, or a custom CoroutineScope
+
+// Never: runBlocking in production code (except main() or tests)
+runBlocking { fetchData() } // Blocks the thread, defeats the purpose
+// Use: suspend functions all the way up
+
+// Never: catching CancellationException without rethrowing
+catch (e: Exception) { log(e) } // Swallows cancellation!
+// Use: catch (e: Exception) { if (e is CancellationException) throw e; log(e) }
+
+// Never: launch without error handling
+launch { riskyWork() } // Exception silently crashes
+// Use: launch with try-catch or CoroutineExceptionHandler
+
+// Never: Thread.sleep() in coroutines
+Thread.sleep(1000) // Blocks the thread
+// Use: delay(1000) // Suspends without blocking
+```