@namch/agent-assistant 1.0.0

package/skills/typescript-expert/scripts/ts_diagnostic.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+TypeScript Project Diagnostic Script
+Analyzes TypeScript projects for configuration, performance, and common issues.
+"""
+
+import subprocess
+import sys
+import os
+import json
+from pathlib import Path
+
+def run_cmd(cmd: str) -> str:
+    """Run shell command and return output."""
+    try:
+        result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
+        return result.stdout + result.stderr
+    except Exception as e:
+        return str(e)
+
+def check_versions():
+    """Check TypeScript and Node versions."""
+    print("\n📦 Versions:")
+    print("-" * 40)
+    
+    ts_version = run_cmd("npx tsc --version 2>/dev/null").strip()
+    node_version = run_cmd("node -v 2>/dev/null").strip()
+    
+    print(f"  TypeScript: {ts_version or 'Not found'}")
+    print(f"  Node.js: {node_version or 'Not found'}")
+
+def check_tsconfig():
+    """Analyze tsconfig.json settings."""
+    print("\n⚙️ TSConfig Analysis:")
+    print("-" * 40)
+    
+    tsconfig_path = Path("tsconfig.json")
+    if not tsconfig_path.exists():
+        print("⚠️ tsconfig.json not found")
+        return
+    
+    try:
+        with open(tsconfig_path) as f:
+            config = json.load(f)
+        
+        compiler_opts = config.get("compilerOptions", {})
+        
+        # Check strict mode
+        if compiler_opts.get("strict"):
+            print("✅ Strict mode enabled")
+        else:
+            print("⚠️ Strict mode NOT enabled")
+        
+        # Check important flags
+        flags = {
+            "noUncheckedIndexedAccess": "Unchecked index access protection",
+            "noImplicitOverride": "Implicit override protection",
+            "skipLibCheck": "Skip lib check (performance)",
+            "incremental": "Incremental compilation"
+        }
+        
+        for flag, desc in flags.items():
+            status = "✅" if compiler_opts.get(flag) else "⚪"
+            print(f"  {status} {desc}: {compiler_opts.get(flag, 'not set')}")
+        
+        # Check module settings
+        print(f"\n  Module: {compiler_opts.get('module', 'not set')}")
+        print(f"  Module Resolution: {compiler_opts.get('moduleResolution', 'not set')}")
+        print(f"  Target: {compiler_opts.get('target', 'not set')}")
+        
+    except json.JSONDecodeError:
+        print("❌ Invalid JSON in tsconfig.json")
+
+def check_tooling():
+    """Detect TypeScript tooling ecosystem."""
+    print("\n🛠️ Tooling Detection:")
+    print("-" * 40)
+    
+    pkg_path = Path("package.json")
+    if not pkg_path.exists():
+        print("⚠️ package.json not found")
+        return
+    
+    try:
+        with open(pkg_path) as f:
+            pkg = json.load(f)
+        
+        all_deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+        
+        tools = {
+            "biome": "Biome (linter/formatter)",
+            "eslint": "ESLint",
+            "prettier": "Prettier",
+            "vitest": "Vitest (testing)",
+            "jest": "Jest (testing)",
+            "turborepo": "Turborepo (monorepo)",
+            "turbo": "Turbo (monorepo)",
+            "nx": "Nx (monorepo)",
+            "lerna": "Lerna (monorepo)"
+        }
+        
+        for tool, desc in tools.items():
+            for dep in all_deps:
+                if tool in dep.lower():
+                    print(f"  ✅ {desc}")
+                    break
+                    
+    except json.JSONDecodeError:
+        print("❌ Invalid JSON in package.json")
+
+def check_monorepo():
+    """Check for monorepo configuration."""
+    print("\n📦 Monorepo Check:")
+    print("-" * 40)
+    
+    indicators = [
+        ("pnpm-workspace.yaml", "PNPM Workspace"),
+        ("lerna.json", "Lerna"),
+        ("nx.json", "Nx"),
+        ("turbo.json", "Turborepo")
+    ]
+    
+    found = False
+    for file, name in indicators:
+        if Path(file).exists():
+            print(f"  ✅ {name} detected")
+            found = True
+    
+    if not found:
+        print("  ⚪ No monorepo configuration detected")
+
+def check_type_errors():
+    """Run quick type check."""
+    print("\n🔍 Type Check:")
+    print("-" * 40)
+    
+    result = run_cmd("npx tsc --noEmit 2>&1 | head -20")
+    if "error TS" in result:
+        errors = result.count("error TS")
+        print(f"  ❌ {errors}+ type errors found")
+        print(result[:500])
+    else:
+        print("  ✅ No type errors")
+
+def check_any_usage():
+    """Check for any type usage."""
+    print("\n⚠️ 'any' Type Usage:")
+    print("-" * 40)
+    
+    result = run_cmd("grep -r ': any' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | wc -l")
+    count = result.strip()
+    if count and count != "0":
+        print(f"  ⚠️ Found {count} occurrences of ': any'")
+        sample = run_cmd("grep -rn ': any' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | head -5")
+        if sample:
+            print(sample)
+    else:
+        print("  ✅ No explicit 'any' types found")
+
+def check_type_assertions():
+    """Check for type assertions."""
+    print("\n⚠️ Type Assertions (as):")
+    print("-" * 40)
+    
+    result = run_cmd("grep -r ' as ' --include='*.ts' --include='*.tsx' src/ 2>/dev/null | grep -v 'import' | wc -l")
+    count = result.strip()
+    if count and count != "0":
+        print(f"  ⚠️ Found {count} type assertions")
+    else:
+        print("  ✅ No type assertions found")
+
+def check_performance():
+    """Check type checking performance."""
+    print("\n⏱️ Type Check Performance:")
+    print("-" * 40)
+    
+    result = run_cmd("npx tsc --extendedDiagnostics --noEmit 2>&1 | grep -E 'Check time|Files:|Lines:|Nodes:'")
+    if result.strip():
+        for line in result.strip().split('\n'):
+            print(f"  {line}")
+    else:
+        print("  ⚠️ Could not measure performance")
+
+def main():
+    print("=" * 50)
+    print("🔍 TypeScript Project Diagnostic Report")
+    print("=" * 50)
+    
+    check_versions()
+    check_tsconfig()
+    check_tooling()
+    check_monorepo()
+    check_any_usage()
+    check_type_assertions()
+    check_type_errors()
+    check_performance()
+    
+    print("\n" + "=" * 50)
+    print("✅ Diagnostic Complete")
+    print("=" * 50)
+
+if __name__ == "__main__":
+    main()

package/skills/typescript-pro/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: typescript-pro
+description: Use when building TypeScript applications requiring advanced type systems, generics, or full-stack type safety. Invoke for type guards, utility types, tRPC integration, monorepo setup.
+triggers:
+  - TypeScript
+  - generics
+  - type safety
+  - conditional types
+  - mapped types
+  - tRPC
+  - tsconfig
+  - type guards
+  - discriminated unions
+role: specialist
+scope: implementation
+output-format: code
+---
+
+# TypeScript Pro
+
+Senior TypeScript specialist with deep expertise in advanced type systems, full-stack type safety, and production-grade TypeScript development.
+
+## Role Definition
+
+You are a senior TypeScript developer with 10+ years of experience. You specialize in TypeScript 5.0+ advanced type system features, full-stack type safety, and build optimization. You create type-safe APIs with zero runtime type errors.
+
+## When to Use This Skill
+
+- Building type-safe full-stack applications
+- Implementing advanced generics and conditional types
+- Setting up tsconfig and build tooling
+- Creating discriminated unions and type guards
+- Implementing end-to-end type safety with tRPC
+- Optimizing TypeScript compilation and bundle size
+
+## Core Workflow
+
+1. **Analyze type architecture** - Review tsconfig, type coverage, build performance
+2. **Design type-first APIs** - Create branded types, generics, utility types
+3. **Implement with type safety** - Write type guards, discriminated unions, conditional types
+4. **Optimize build** - Configure project references, incremental compilation, tree shaking
+5. **Test types** - Verify type coverage, test type logic, ensure zero runtime errors
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Advanced Types | `references/advanced-types.md` | Generics, conditional types, mapped types, template literals |
+| Type Guards | `references/type-guards.md` | Type narrowing, discriminated unions, assertion functions |
+| Utility Types | `references/utility-types.md` | Partial, Pick, Omit, Record, custom utilities |
+| Configuration | `references/configuration.md` | tsconfig options, strict mode, project references |
+| Patterns | `references/patterns.md` | Builder pattern, factory pattern, type-safe APIs |
+
+## Constraints
+
+### MUST DO
+- Enable strict mode with all compiler flags
+- Use type-first API design
+- Implement branded types for domain modeling
+- Use `satisfies` operator for type validation
+- Create discriminated unions for state machines
+- Use `Annotated` pattern with type predicates
+- Generate declaration files for libraries
+- Optimize for type inference
+
+### MUST NOT DO
+- Use explicit `any` without justification
+- Skip type coverage for public APIs
+- Mix type-only and value imports
+- Disable strict null checks
+- Use `as` assertions without necessity
+- Ignore compiler performance warnings
+- Skip declaration file generation
+- Use enums (prefer const objects with `as const`)
+
+## Output Templates
+
+When implementing TypeScript features, provide:
+1. Type definitions (interfaces, types, generics)
+2. Implementation with type guards
+3. tsconfig configuration if needed
+4. Brief explanation of type design decisions
+
+## Knowledge Reference
+
+TypeScript 5.0+, generics, conditional types, mapped types, template literal types, discriminated unions, type guards, branded types, tRPC, project references, incremental compilation, declaration files, const assertions, satisfies operator
+
+## Related Skills
+
+- **React Developer** - Component type safety
+- **Fullstack Guardian** - End-to-end type safety
+- **API Designer** - Type-safe API contracts

package/skills/typescript-pro/references/advanced-types.md

@@ -0,0 +1,262 @@
+# Advanced Types
+
+> Reference for: TypeScript Pro
+> Load when: Generics, conditional types, mapped types, template literals
+
+## Generic Constraints
+
+```typescript
+// Basic constraint
+function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+
+// Multiple constraints
+interface HasId { id: number; }
+interface HasName { name: string; }
+
+function merge<T extends HasId, U extends HasName>(obj1: T, obj2: U): T & U {
+  return { ...obj1, ...obj2 };
+}
+
+// Generic constraint with default
+type ApiResponse<T = unknown, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+
+// Constraint with infer
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+type Result = UnwrapPromise<Promise<string>>; // string
+```
+
+## Conditional Types
+
+```typescript
+// Basic conditional type
+type IsString<T> = T extends string ? true : false;
+
+// Distributive conditional types
+type ToArray<T> = T extends any ? T[] : never;
+type StringOrNumberArray = ToArray<string | number>; // string[] | number[]
+
+// Non-distributive (use tuple)
+type ToArrayNonDist<T> = [T] extends [any] ? T[] : never;
+type BothArray = ToArrayNonDist<string | number>; // (string | number)[]
+
+// Nested conditionals for type extraction
+type Flatten<T> = T extends Array<infer U>
+  ? U extends Array<infer V>
+    ? Flatten<V>
+    : U
+  : T;
+
+type Nested = Flatten<string[][][]>; // string
+
+// Exclude null/undefined
+type NonNullable<T> = T extends null | undefined ? never : T;
+```
+
+## Mapped Types
+
+```typescript
+// Basic mapped type
+type ReadOnly<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+// Optional properties
+type Partial<T> = {
+  [K in keyof T]?: T[K];
+};
+
+// Required properties
+type Required<T> = {
+  [K in keyof T]-?: T[K]; // Remove optional modifier
+};
+
+// Key remapping with 'as'
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+interface Person {
+  name: string;
+  age: number;
+}
+
+type PersonGetters = Getters<Person>;
+// { getName: () => string; getAge: () => number; }
+
+// Filtering keys
+type PickByType<T, U> = {
+  [K in keyof T as T[K] extends U ? K : never]: T[K];
+};
+
+type StringFields = PickByType<Person, string>; // { name: string }
+```
+
+## Template Literal Types
+
+```typescript
+// Basic template literal
+type EmailLocale = 'en' | 'es' | 'fr';
+type EmailType = 'welcome' | 'reset-password';
+type EmailTemplate = `${EmailLocale}_${EmailType}`;
+// 'en_welcome' | 'en_reset-password' | 'es_welcome' | ...
+
+// Intrinsic string manipulation
+type Uppercase<S extends string> = intrinsic;
+type Lowercase<S extends string> = intrinsic;
+type Capitalize<S extends string> = intrinsic;
+type Uncapitalize<S extends string> = intrinsic;
+
+type EventName<T extends string> = `on${Capitalize<T>}`;
+type ClickEvent = EventName<'click'>; // 'onClick'
+
+// Template literal with mapped types
+type CSSProperties = {
+  [K in 'color' | 'background' | 'border' as `--${K}`]: string;
+};
+// { '--color': string; '--background': string; '--border': string }
+
+// Pattern matching with infer
+type ExtractRouteParams<T extends string> =
+  T extends `${infer _Start}/:${infer Param}/${infer Rest}`
+    ? Param | ExtractRouteParams<`/${Rest}`>
+    : T extends `${infer _Start}/:${infer Param}`
+    ? Param
+    : never;
+
+type Params = ExtractRouteParams<'/users/:id/posts/:postId'>; // 'id' | 'postId'
+```
+
+## Higher-Kinded Types (Simulation)
+
+```typescript
+// Type-level function simulation
+interface TypeClass<F> {
+  map: <A, B>(f: (a: A) => B, fa: any) => any;
+}
+
+// Functor pattern
+type Maybe<T> = { type: 'just'; value: T } | { type: 'nothing' };
+
+const MaybeFunctor: TypeClass<Maybe<any>> = {
+  map: <A, B>(f: (a: A) => B, ma: Maybe<A>): Maybe<B> => {
+    return ma.type === 'just'
+      ? { type: 'just', value: f(ma.value) }
+      : { type: 'nothing' };
+  }
+};
+
+// Builder pattern with generics
+type Builder<T, K extends keyof T = never> = {
+  with<P extends Exclude<keyof T, K>>(
+    key: P,
+    value: T[P]
+  ): Builder<T, K | P>;
+  build(): K extends keyof T ? T : never;
+};
+```
+
+## Recursive Types
+
+```typescript
+// JSON type
+type JSONValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONValue[]
+  | { [key: string]: JSONValue };
+
+// Deep partial
+type DeepPartial<T> = T extends object ? {
+  [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+// Deep readonly
+type DeepReadonly<T> = T extends object ? {
+  readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+
+// Path type for nested objects
+type PathsToProps<T> = T extends object ? {
+  [K in keyof T]: K extends string
+    ? T[K] extends object
+      ? K | `${K}.${PathsToProps<T[K]>}`
+      : K
+    : never;
+}[keyof T] : never;
+
+interface User {
+  profile: {
+    name: string;
+    settings: {
+      theme: string;
+    };
+  };
+}
+
+type UserPaths = PathsToProps<User>;
+// 'profile' | 'profile.name' | 'profile.settings' | 'profile.settings.theme'
+```
+
+## Variance and Contravariance
+
+```typescript
+// Covariance (return types)
+type Producer<T> = () => T;
+let stringProducer: Producer<string> = () => 'hello';
+let objectProducer: Producer<object> = stringProducer; // OK: string is object
+
+// Contravariance (parameter types)
+type Consumer<T> = (value: T) => void;
+let objectConsumer: Consumer<object> = (obj) => console.log(obj);
+let stringConsumer: Consumer<string> = objectConsumer; // OK in strict mode
+
+// Invariance (mutable properties)
+interface Box<T> {
+  value: T;
+  setValue(v: T): void;
+}
+
+let stringBox: Box<string> = { value: '', setValue: (v) => {} };
+// let objectBox: Box<object> = stringBox; // Error: invariant
+```
+
+## Type-Level Programming
+
+```typescript
+// Type-level addition (limited)
+type Length<T extends any[]> = T['length'];
+type Concat<A extends any[], B extends any[]> = [...A, ...B];
+
+// Type-level conditionals
+type If<Condition extends boolean, Then, Else> =
+  Condition extends true ? Then : Else;
+
+// Type-level equality
+type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends
+  (<T>() => T extends Y ? 1 : 2) ? true : false;
+
+// Assert equal types (for testing)
+type Assert<T extends true> = T;
+type Test = Assert<Equal<1 | 2, 2 | 1>>; // OK
+```
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| `T extends U ? X : Y` | Conditional type logic |
+| `infer R` | Extract types from patterns |
+| `K in keyof T` | Iterate over object keys |
+| `as NewKey` | Remap keys in mapped types |
+| Template literals | String pattern types |
+| `T extends any` | Distributive conditionals |
+| `[T] extends [any]` | Non-distributive check |
+| `-?` modifier | Remove optional |
+| `readonly` modifier | Make immutable |