@biggora/claude-plugins 1.2.0 → 1.3.0

package/src/skills/typescript-expert/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: typescript-expert
+description: TypeScript language expertise covering the type system, generics, utility types, advanced type patterns, and project configuration. Use this skill whenever writing, reviewing, or refactoring TypeScript code, designing type-safe APIs, working with complex generics, debugging type errors, configuring tsconfig.json, migrating JavaScript to TypeScript, or leveraging TypeScript 5.x features like satisfies, const type parameters, decorators, and the using keyword. Also use when the user asks about type narrowing, conditional types, mapped types, template literal types, branded types, discriminated unions, or any TypeScript type system question — even seemingly simple ones, because TypeScript's type system has subtle gotchas that catch experienced developers.
+---
+
+# TypeScript Expert
+
+> Covers TypeScript through 5.8 (latest stable as of March 2026). The official handbook at https://www.typescriptlang.org/docs/handbook/ is the canonical reference.
+
+TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Its type system is structural (not nominal), meaning type compatibility is determined by shape rather than declaration. This has profound implications for how you design types and APIs.
+
+## Quick Decision Guide
+
+| You need to... | Read |
+|----------------|------|
+| Understand primitives, inference, narrowing | [core-type-system](references/core-type-system.md) |
+| Choose between `interface` and `type` | [core-interfaces-types](references/core-interfaces-types.md) |
+| Write generic functions, classes, constraints | [core-generics](references/core-generics.md) |
+| Use `Partial`, `Pick`, `Omit`, `Record`, etc. | [core-utility-types](references/core-utility-types.md) |
+| Build conditional types with `infer` | [advanced-conditional-types](references/advanced-conditional-types.md) |
+| Create mapped types and key remapping | [advanced-mapped-types](references/advanced-mapped-types.md) |
+| Use template literal types for string patterns | [advanced-template-literals](references/advanced-template-literals.md) |
+| Narrow types with guards and discriminated unions | [advanced-type-guards](references/advanced-type-guards.md) |
+| Use TC39 decorators (TS 5.0+) | [advanced-decorators](references/advanced-decorators.md) |
+| Configure `tsconfig.json` properly | [best-practices-tsconfig](references/best-practices-tsconfig.md) |
+| Apply common patterns (branded types, error handling, immutability) | [best-practices-patterns](references/best-practices-patterns.md) |
+| Optimize type-level performance | [best-practices-performance](references/best-practices-performance.md) |
+| Use TS 5.0-5.8 features (`satisfies`, `const` params, `using`) | [features-ts5x](references/features-ts5x.md) |
+
+## Core Principles
+
+### 1. Let TypeScript Infer
+
+TypeScript's inference is powerful. Don't annotate what TypeScript can figure out on its own:
+
+```typescript
+// Unnecessary — TypeScript infers `number`
+const count: number = 5;
+
+// Good — let inference work
+const count = 5;
+
+// DO annotate function signatures (parameters + return types for public APIs)
+function getUser(id: string): Promise<User> { ... }
+
+// Return type annotation catches accidental returns
+function parse(input: string): ParseResult {
+  if (!input) return null; // Error! null isn't ParseResult — good, we caught a bug
+}
+```
+
+### 2. Prefer `unknown` over `any`
+
+`any` disables type checking. `unknown` is type-safe — you must narrow it before use:
+
+```typescript
+// Bad — silently breaks type safety
+function process(data: any) {
+  data.foo.bar; // No error, but might crash at runtime
+}
+
+// Good — forces you to check before using
+function process(data: unknown) {
+  if (typeof data === "object" && data !== null && "foo" in data) {
+    // Now TypeScript knows data has a foo property
+  }
+}
+```
+
+### 3. Use Strict Mode
+
+Always enable `"strict": true` in tsconfig.json. It enables all strict type-checking flags including `strictNullChecks`, `noImplicitAny`, and `strictFunctionTypes`. Projects that skip strict mode accumulate hidden bugs that surface painfully later. See [best-practices-tsconfig](references/best-practices-tsconfig.md) for the full recommended configuration.
+
+### 4. Model Your Domain with Types
+
+The type system is a tool for encoding business rules. Use discriminated unions to model states, branded types for domain identifiers, and `readonly` to enforce immutability:
+
+```typescript
+// Model states explicitly — impossible to access data in loading/error state
+type AsyncState<T> =
+  | { status: "loading" }
+  | { status: "error"; error: Error }
+  | { status: "success"; data: T };
+
+// Branded types prevent ID mixups at compile time
+type UserId = string & { readonly __brand: "UserId" };
+type OrderId = string & { readonly __brand: "OrderId" };
+
+function getOrder(orderId: OrderId): Order { ... }
+getOrder(userId); // Error! UserId is not assignable to OrderId
+```
+
+### 5. Structural Typing Implications
+
+TypeScript uses structural typing — if two types have the same shape, they're compatible:
+
+```typescript
+interface Point { x: number; y: number }
+interface Coordinate { x: number; y: number }
+
+const p: Point = { x: 1, y: 2 };
+const c: Coordinate = p; // OK — same shape
+
+// This means excess property checks only apply to object literals
+function plot(point: Point) { ... }
+plot({ x: 1, y: 2, z: 3 }); // Error — excess property check on literal
+const obj = { x: 1, y: 2, z: 3 };
+plot(obj); // OK — no excess check on variable
+```
+
+## Common Gotchas
+
+| Gotcha | Explanation |
+|--------|-------------|
+| `object` vs `Object` vs `{}` | Use `object` for non-primitives. Never use `Object` or `{}` as types — `{}` matches everything except `null`/`undefined`. |
+| `T[]` vs `readonly T[]` | Arrays are mutable by default. Use `readonly T[]` or `ReadonlyArray<T>` when mutation isn't intended. |
+| `enum` vs union | Prefer union types (`type Dir = "N" \| "S" \| "E" \| "W"`) over enums. Enums produce runtime code and have subtle nominal typing behavior. Use `as const` objects if you need runtime values. |
+| Optional vs `undefined` | `{ x?: number }` means x may be missing entirely. `{ x: number \| undefined }` means x must be present but can be undefined. These behave differently with `in` checks and spread. |
+| `as` casts | Type assertions (`as`) override the compiler. Prefer type guards for runtime narrowing. Use `as` only when you genuinely know more than TypeScript. |
+| `any` propagation | A single `any` silently infects surrounding types. Use `unknown` and narrow, or use `// @ts-expect-error` for known edge cases. |
+
+## TypeScript 5.x Highlights
+
+Key features added in TypeScript 5.0-5.8 (see [features-ts5x](references/features-ts5x.md) for details):
+
+| Version | Feature | Why it matters |
+|---------|---------|----------------|
+| 5.0 | TC39 Decorators | Standard decorator syntax, no `experimentalDecorators` needed |
+| 5.0 | `const` type parameters | `<const T>` gives const-like inference without `as const` at call site |
+| 5.1 | Easier implicit returns | `undefined`-returning functions can omit `return` |
+| 5.2 | `using` declarations | Deterministic resource cleanup (like C# `using` / Python `with`) |
+| 5.4 | `NoInfer<T>` | Prevents unwanted inference from specific positions |
+| 5.5 | Inferred type predicates | `filter(Boolean)` and arrow guards just work |
+| 5.6 | Iterator helper methods | `.map()`, `.filter()`, `.take()` on iterators |
+| 5.7 | `--squash` for project refs | Faster composite project builds |
+| 5.8 | `--erasableSyntaxOnly` | Strip types without full compilation (Node.js `--strip-types` support) |
+
+## When to Read the References
+
+- **Writing a new module/library**: Read [core-generics](references/core-generics.md) and [best-practices-patterns](references/best-practices-patterns.md)
+- **Debugging a confusing type error**: Read [advanced-type-guards](references/advanced-type-guards.md) and [core-type-system](references/core-type-system.md)
+- **Designing a type-safe API**: Read [advanced-conditional-types](references/advanced-conditional-types.md) and [advanced-mapped-types](references/advanced-mapped-types.md)
+- **Setting up a new project**: Read [best-practices-tsconfig](references/best-practices-tsconfig.md)
+- **Migrating from JS or older TS**: Read [features-ts5x](references/features-ts5x.md) and [best-practices-tsconfig](references/best-practices-tsconfig.md)
+- **Performance issues with types**: Read [best-practices-performance](references/best-practices-performance.md)

package/src/skills/typescript-expert/commands/typescript-fix.md

@@ -0,0 +1,65 @@
+---
+description: Run TypeScript type-checking and resolve all errors using the typescript-expert skill
+allowed-tools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
+---
+
+You are a TypeScript expert with deep expertise in advanced typing patterns, modern JavaScript (ES6+), and enterprise-grade development practices. You specialize in building reliable, maintainable, and performant TypeScript solutions for complex business problems, with a solid understanding of JavaScript fundamentals and code quality tools.
+
+Use the `typescript-expert` skill for reference when resolving complex type issues — it covers generics, conditional types, mapped types, utility types, type guards, discriminated unions, and TypeScript 5.x features.
+
+## Step 1: Detect the Project Setup
+
+Read `package.json` to determine:
+- The package manager in use (`npm`, `pnpm`, `yarn`, or `bun`) — check for lock files (`pnpm-lock.yaml`, `yarn.lock`, `bun.lockb`, `package-lock.json`)
+- Whether a `typecheck` script exists in `scripts` (e.g., `"typecheck": "tsc --noEmit"`)
+- The TypeScript version installed
+- Any relevant type-checking plugins (e.g., `vue-tsc`, `astro check`)
+
+Read `tsconfig.json` (and any extended configs like `tsconfig.app.json`) to understand:
+- The `strict` settings in effect
+- The `include`/`exclude` paths
+- Module resolution strategy
+- Any path aliases
+
+## Step 2: Run Type-Checking
+
+Run the appropriate command based on what you found:
+
+1. **If a `typecheck` script exists**: `npm run typecheck` / `pnpm run typecheck` / `yarn typecheck`
+2. **If no script but `tsc` is available**: `npx tsc --noEmit`
+3. **For monorepos**: Check if there's a root-level typecheck or per-package scripts
+
+Capture the full output. If there are no errors, report success and stop.
+
+## Step 3: Analyze and Categorize Errors
+
+Group errors by category before fixing:
+
+- **Missing types**: `Cannot find module` or `Could not find a declaration file` — need `@types/*` packages or declaration files
+- **Strict null violations**: `Object is possibly 'null' or 'undefined'` — need null checks or non-null assertions
+- **Type mismatches**: `Type 'X' is not assignable to type 'Y'` — need type corrections, guards, or generics
+- **Missing properties**: `Property 'X' does not exist on type 'Y'` — need interface extensions or type narrowing
+- **Import issues**: `Module has no exported member` — need import corrections or type augmentation
+- **Generic constraints**: `Type 'T' does not satisfy the constraint` — need constraint adjustments
+
+## Step 4: Fix Errors Systematically
+
+Work through errors file-by-file, starting with root causes (a single fix often resolves multiple downstream errors):
+
+1. **Fix type declaration issues first** — missing `@types/*`, incorrect `d.ts` files, or module augmentations
+2. **Fix interface/type definitions** — incorrect shapes propagate errors everywhere
+3. **Fix implementation code** — narrowing, guards, assertions, generic constraints
+4. **Fix edge cases** — strict null checks, index access, exhaustiveness
+
+For each fix:
+- Read the file and understand the context around the error
+- Apply the minimal correct fix — don't over-annotate or use `any` as an escape hatch
+- Prefer type narrowing and guards over type assertions (`as`)
+- Use `unknown` instead of `any` when the type is truly unknown
+- Add `// @ts-expect-error` only as a last resort, with a comment explaining why
+
+## Step 5: Verify
+
+Re-run the type-check command from Step 2. If errors remain, go back to Step 3 with the new output. Repeat until clean.
+
+Report the final result: how many errors were found, how many were fixed, and what changes were made.

package/src/skills/typescript-expert/references/advanced-conditional-types.md

@@ -0,0 +1,190 @@
+# Conditional Types
+
+Conditional types select one of two types based on a condition, enabling type-level logic similar to ternary expressions.
+
+## Basic Syntax
+
+```typescript
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<"hello">;  // true
+type B = IsString<42>;        // false
+```
+
+The syntax is `T extends U ? X : Y` — if `T` is assignable to `U`, the result is `X`, otherwise `Y`.
+
+## The `infer` Keyword
+
+`infer` declares a type variable within a conditional type, extracting parts of a type:
+
+```typescript
+// Extract the element type from an array
+type ElementType<T> = T extends (infer E)[] ? E : never;
+type A = ElementType<string[]>;  // string
+type B = ElementType<number>;    // never
+
+// Extract the return type of a function
+type MyReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+type C = MyReturnType<() => string>;  // string
+
+// Extract promise inner type
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+type D = UnwrapPromise<Promise<number>>;  // number
+type E = UnwrapPromise<string>;            // string
+
+// Multiple infer positions
+type FirstArg<T> = T extends (first: infer F, ...rest: any[]) => any ? F : never;
+type F = FirstArg<(name: string, age: number) => void>;  // string
+```
+
+### `infer` with Constraints (TS 4.7+)
+
+You can constrain what `infer` matches:
+
+```typescript
+// Only infer if the element is a string
+type StringElements<T> = T extends (infer E extends string)[] ? E : never;
+type G = StringElements<["a", "b", "c"]>;  // "a" | "b" | "c"
+type H = StringElements<[1, 2, 3]>;         // never
+```
+
+## Distributive Conditional Types
+
+When a conditional type acts on a **naked type parameter** (not wrapped in `[]`, `Promise<>`, etc.), it distributes over union types:
+
+```typescript
+type ToArray<T> = T extends any ? T[] : never;
+
+// Distributes: applies to each union member separately
+type A = ToArray<string | number>;  // string[] | number[]
+
+// Compare with non-distributive version:
+type ToArrayND<T> = [T] extends [any] ? T[] : never;
+type B = ToArrayND<string | number>;  // (string | number)[]
+```
+
+### Preventing Distribution
+
+Wrap both sides in `[]` to prevent distribution:
+
+```typescript
+type IsNever<T> = [T] extends [never] ? true : false;
+
+type A = IsNever<never>;   // true
+type B = IsNever<string>;  // false
+
+// Without brackets, never distributes to... nothing
+type IsNeverBad<T> = T extends never ? true : false;
+type C = IsNeverBad<never>;  // never (not true!)
+```
+
+## Practical Patterns
+
+### Filtering Union Members
+
+```typescript
+// Keep only object types from a union
+type ObjectsOnly<T> = T extends object ? T : never;
+type Mixed = string | { a: 1 } | number | { b: 2 };
+type OnlyObjects = ObjectsOnly<Mixed>;  // { a: 1 } | { b: 2 }
+
+// Keep only functions
+type FunctionsOnly<T> = T extends (...args: any[]) => any ? T : never;
+```
+
+### Recursive Conditional Types
+
+```typescript
+// Deeply unwrap promises
+type DeepAwaited<T> = T extends Promise<infer U> ? DeepAwaited<U> : T;
+type A = DeepAwaited<Promise<Promise<Promise<string>>>>;  // string
+
+// Flatten nested arrays
+type Flatten<T> = T extends (infer E)[] ? Flatten<E> : T;
+type B = Flatten<number[][][]>;  // number
+```
+
+### Extracting Based on Shape
+
+```typescript
+// Extract event handlers from an object type
+type EventHandlers<T> = {
+  [K in keyof T as T[K] extends (...args: any[]) => any ? K : never]: T[K];
+};
+
+interface Component {
+  onClick: (e: MouseEvent) => void;
+  onHover: (e: MouseEvent) => void;
+  className: string;
+  id: string;
+}
+
+type Handlers = EventHandlers<Component>;
+// { onClick: (e: MouseEvent) => void; onHover: (e: MouseEvent) => void }
+```
+
+### Conditional Return Types
+
+```typescript
+// Function overload via conditional types
+function process<T extends string | number>(
+  value: T
+): T extends string ? string[] : number {
+  if (typeof value === "string") {
+    return value.split("") as any;
+  }
+  return (value * 2) as any;
+}
+
+const a = process("hello");  // string[]
+const b = process(42);        // number
+```
+
+Note: Conditional return types often require `as any` inside the implementation because TypeScript can't narrow generic types. This is one of the few legitimate uses of `as any`.
+
+### Type-Level Assertions
+
+```typescript
+// Ensure a type satisfies a condition at the type level
+type Assert<T extends true> = T;
+type IsEqual<A, B> = [A] extends [B] ? [B] extends [A] ? true : false : false;
+
+// Compile-time test
+type _test = Assert<IsEqual<string, string>>;  // OK
+// type _test2 = Assert<IsEqual<string, number>>;  // Error!
+```
+
+## Common Utility Implementations
+
+```typescript
+// Built-in Exclude
+type MyExclude<T, U> = T extends U ? never : T;
+
+// Built-in Extract
+type MyExtract<T, U> = T extends U ? T : never;
+
+// Built-in NonNullable
+type MyNonNullable<T> = T extends null | undefined ? never : T;
+
+// Built-in Parameters
+type MyParameters<T extends (...args: any) => any> =
+  T extends (...args: infer P) => any ? P : never;
+
+// Built-in ReturnType
+type MyReturnType<T extends (...args: any) => any> =
+  T extends (...args: any) => infer R ? R : any;
+```
+
+## Gotchas
+
+1. **`never` in conditionals**: `never` distributes to nothing. Use `[T] extends [never]` to check for never.
+
+2. **`any` in conditionals**: `any` produces a union of both branches:
+   ```typescript
+   type Test<T> = T extends string ? "yes" : "no";
+   type X = Test<any>;  // "yes" | "no"
+   ```
+
+3. **Depth limits**: TypeScript has a recursion depth limit (~50 levels). Deep recursive types may hit it.
+
+4. **Assignability of conditional types**: TypeScript often can't resolve conditional types involving unresolved generics. Inside a generic function, `T extends X ? A : B` remains unresolved.

package/src/skills/typescript-expert/references/advanced-decorators.md

@@ -0,0 +1,243 @@
+# TC39 Decorators (TypeScript 5.0+)
+
+TypeScript 5.0 introduced support for the TC39 Stage 3 decorator proposal. These are **not** the same as legacy `experimentalDecorators` — they have different semantics, no `reflect-metadata`, and work without any compiler flag.
+
+## When to Use Which
+
+- **TC39 decorators** (default, no flag): The standard going forward. Use for new code.
+- **`experimentalDecorators`** (tsconfig flag): Legacy. Required by Angular, NestJS, TypeORM, and other frameworks that depend on `reflect-metadata`. Keep using if your framework requires it.
+
+Check your framework's documentation — many are migrating to TC39 decorators.
+
+## Class Decorators
+
+```typescript
+// A class decorator receives the class itself and an optional context
+function sealed(target: Function, context: ClassDecoratorContext) {
+  Object.seal(target);
+  Object.seal(target.prototype);
+}
+
+@sealed
+class Greeter {
+  greeting: string;
+  constructor(message: string) {
+    this.greeting = message;
+  }
+}
+```
+
+### Adding Functionality
+
+```typescript
+function withTimestamp<T extends new (...args: any[]) => any>(
+  target: T,
+  context: ClassDecoratorContext
+) {
+  return class extends target {
+    createdAt = new Date();
+  };
+}
+
+@withTimestamp
+class User {
+  name: string;
+  constructor(name: string) { this.name = name; }
+}
+```
+
+## Method Decorators
+
+```typescript
+function log(
+  target: Function,
+  context: ClassMethodDecoratorContext
+) {
+  const methodName = String(context.name);
+  return function (this: any, ...args: any[]) {
+    console.log(`Calling ${methodName} with`, args);
+    const result = target.call(this, ...args);
+    console.log(`${methodName} returned`, result);
+    return result;
+  };
+}
+
+class Calculator {
+  @log
+  add(a: number, b: number): number {
+    return a + b;
+  }
+}
+```
+
+### Bound Method Decorator
+
+```typescript
+function bound(
+  target: Function,
+  context: ClassMethodDecoratorContext
+) {
+  const methodName = context.name;
+  context.addInitializer(function (this: any) {
+    this[methodName] = this[methodName].bind(this);
+  });
+}
+
+class Button {
+  label = "Click me";
+
+  @bound
+  handleClick() {
+    console.log(this.label); // Always correct `this`
+  }
+}
+```
+
+## Field Decorators
+
+```typescript
+function min(minValue: number) {
+  return function (
+    target: undefined, // field decorators receive undefined
+    context: ClassFieldDecoratorContext
+  ) {
+    return function (initialValue: number) {
+      if (initialValue < minValue) {
+        throw new Error(`${String(context.name)} must be >= ${minValue}`);
+      }
+      return initialValue;
+    };
+  };
+}
+
+class Product {
+  @min(0)
+  price: number;
+
+  constructor(price: number) {
+    this.price = price;
+  }
+}
+```
+
+## Accessor Decorators
+
+The `accessor` keyword (TS 5.0+) creates auto-accessor fields with implicit getter/setter:
+
+```typescript
+class Person {
+  accessor name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+// Decorator for accessors
+function validate(
+  target: ClassAccessorDecoratorTarget<any, string>,
+  context: ClassAccessorDecoratorContext
+) {
+  return {
+    set(value: string) {
+      if (!value.trim()) throw new Error(`${String(context.name)} cannot be empty`);
+      target.set.call(this, value);
+    },
+    get() {
+      return target.get.call(this);
+    },
+  };
+}
+
+class User {
+  @validate
+  accessor name: string = "";
+}
+```
+
+## Decorator Factories
+
+Most real-world decorators are factories — functions that return decorators:
+
+```typescript
+function retry(attempts: number) {
+  return function (
+    target: Function,
+    context: ClassMethodDecoratorContext
+  ) {
+    return async function (this: any, ...args: any[]) {
+      for (let i = 0; i < attempts; i++) {
+        try {
+          return await target.call(this, ...args);
+        } catch (err) {
+          if (i === attempts - 1) throw err;
+        }
+      }
+    };
+  };
+}
+
+class ApiClient {
+  @retry(3)
+  async fetchData(url: string): Promise<Response> {
+    return fetch(url);
+  }
+}
+```
+
+## Decorator Context Types
+
+Each decorator kind has a specific context type:
+
+| Decorator Target | Context Type |
+|------------------|-------------|
+| Class | `ClassDecoratorContext` |
+| Method | `ClassMethodDecoratorContext` |
+| Getter | `ClassGetterDecoratorContext` |
+| Setter | `ClassSetterDecoratorContext` |
+| Field | `ClassFieldDecoratorContext` |
+| Auto-accessor | `ClassAccessorDecoratorContext` |
+
+All context types include:
+- `name`: The name of the decorated element
+- `kind`: "class", "method", "getter", "setter", "field", or "accessor"
+- `static`: Whether the element is static
+- `private`: Whether the element is private
+- `addInitializer()`: Register a callback to run during construction
+- `metadata`: Shared metadata object (replaces `reflect-metadata`)
+
+## Metadata (TC39 Decorator Metadata)
+
+TC39 decorators have a built-in metadata mechanism:
+
+```typescript
+function meta(key: string, value: any) {
+  return function (_target: any, context: ClassMethodDecoratorContext) {
+    context.metadata[key] = value;
+  };
+}
+
+class Routes {
+  @meta("path", "/users")
+  @meta("method", "GET")
+  getUsers() { ... }
+}
+
+// Access metadata
+const metadata = Routes[Symbol.metadata];
+// { path: "/users", method: "GET" }
+```
+
+## Migration from `experimentalDecorators`
+
+Key differences:
+
+| `experimentalDecorators` | TC39 Decorators |
+|--------------------------|-----------------|
+| Receives `(target, key, descriptor)` | Receives `(value, context)` |
+| Uses `reflect-metadata` for metadata | Uses `context.metadata` |
+| Parameter decorators supported | No parameter decorators |
+| `emitDecoratorMetadata` flag | No equivalent (use `context.metadata`) |
+| Runs at class definition time | Runs at class definition time |
+
+Parameter decorators are **not** part of TC39 decorators. Frameworks that need them (like NestJS for DI) still require `experimentalDecorators`.