@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/gemini-cli/ts-mapped-types/SKILL.md

@@ -0,0 +1,147 @@
+# TypeScript Mapped Types
+
+> Transform object types by iterating over their keys with mapped type syntax
+
+## When to Use
+
+- Creating new types by transforming all properties of an existing type
+- Making all properties optional, readonly, or nullable
+- Remapping keys to create derived property names
+- Building type-safe form state, API response wrappers, or configuration objects
+
+## Instructions
+
+1. **Basic mapped type** — iterate over keys with `in keyof`:
+
+```typescript
+type Readonly<T> = {
+  readonly [K in keyof T]: T[K];
+};
+
+type Optional<T> = {
+  [K in keyof T]?: T[K];
+};
+```
+
+2. **Add or remove modifiers** with `+` and `-`:
+
+```typescript
+type Mutable<T> = {
+  -readonly [K in keyof T]: T[K];
+};
+
+type Required<T> = {
+  [K in keyof T]-?: T[K];
+};
+```
+
+3. **Transform value types:**
+
+```typescript
+type Nullable<T> = {
+  [K in keyof T]: T[K] | null;
+};
+
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+type User = { name: string; age: number };
+type UserGetters = Getters<User>;
+// { getName: () => string; getAge: () => number }
+```
+
+4. **Key remapping with `as`:**
+
+```typescript
+type PrefixedKeys<T, P extends string> = {
+  [K in keyof T as `${P}${Capitalize<string & K>}`]: T[K];
+};
+
+type ApiUser = PrefixedKeys<User, 'user'>;
+// { userName: string; userAge: number }
+```
+
+5. **Filter keys with `as` and `never`:**
+
+```typescript
+type OnlyStrings<T> = {
+  [K in keyof T as T[K] extends string ? K : never]: T[K];
+};
+
+type StringFields = OnlyStrings<{ name: string; age: number; email: string }>;
+// { name: string; email: string }
+```
+
+6. **Map over a union of string literals:**
+
+```typescript
+type EventHandlers<T extends string> = {
+  [K in T as `on${Capitalize<K>}`]: (event: K) => void;
+};
+
+type Handlers = EventHandlers<'click' | 'hover' | 'focus'>;
+// { onClick: (event: 'click') => void; onHover: ...; onFocus: ... }
+```
+
+7. **Combine with conditional types:**
+
+```typescript
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+```
+
+8. **Practical patterns:**
+
+```typescript
+// Form state with touched/error tracking
+type FormState<T> = {
+  values: T;
+  touched: { [K in keyof T]: boolean };
+  errors: { [K in keyof T]?: string };
+};
+
+// Pick and transform
+type PickAndNullify<T, K extends keyof T> = {
+  [P in K]: T[P] | null;
+};
+```
+
+## Details
+
+Mapped types iterate over a set of keys (from `keyof T` or a string literal union) and produce a new object type with one property per key. They are the foundation of most built-in utility types (`Partial`, `Required`, `Readonly`, `Pick`, `Record`).
+
+**Homomorphic mapped types:** When the key source is `keyof T`, the mapped type preserves optional and readonly modifiers from the original type. This is why `Partial<T>` works correctly on types that already have optional properties.
+
+**Key remapping (TypeScript 4.1+):** The `as` clause in a mapped type lets you transform key names, filter keys (by mapping to `never`), or create entirely new key sets from the original keys.
+
+**Template literal types + mapped types:** Combining `as \`prefix${K}\`` with mapped types creates patterns like getter/setter generation, event handler typing, and API route typing.
+
+**Recursive mapped types:** TypeScript allows recursive mapped types for deep transformations (`DeepPartial`, `DeepReadonly`). The compiler has a recursion depth limit — extremely deep object nesting can cause issues.
+
+**Trade-offs:**
+
+- Mapped types produce clear, readable type transformations but complex mapped types can be hard to debug
+- Key remapping with `as` is powerful but the type error messages when it fails are often cryptic
+- Recursive mapped types can slow the compiler on deeply nested structures
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/mapped-types.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/ts-mapped-types/skill.yaml

@@ -0,0 +1,39 @@
+name: ts-mapped-types
+version: "1.0.0"
+description: Transform object types by iterating over their keys with mapped type syntax
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "tsconfig.json"
+  - "tsconfig.*.json"
+related_skills:
+  - ts-generics-pattern
+  - ts-utility-types
+  - ts-conditional-types
+stack_signals:
+  - typescript
+keywords:
+  - mapped-types
+  - keyof
+  - homomorphic
+  - as-clause
+  - modifiers
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/mapped-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ts-module-patterns/SKILL.md

@@ -0,0 +1,156 @@
+# TypeScript Module Patterns
+
+> Organize TypeScript code with ES modules, barrel exports, path aliases, and declaration files
+
+## When to Use
+
+- Structuring a TypeScript project's import/export architecture
+- Setting up barrel files (index.ts re-exports) for clean public APIs
+- Configuring path aliases to avoid deep relative imports
+- Creating or consuming declaration files (.d.ts)
+
+## Instructions
+
+1. **Use named exports** over default exports for better refactoring and tree-shaking:
+
+```typescript
+// user.ts
+export interface User {
+  id: string;
+  name: string;
+}
+export function createUser(name: string): User {
+  /* ... */
+}
+
+// consumer.ts
+import { User, createUser } from './user';
+```
+
+2. **Barrel files** — re-export from `index.ts` to create clean module boundaries:
+
+```typescript
+// features/auth/index.ts
+export { AuthProvider } from './auth-provider';
+export { useAuth } from './use-auth';
+export type { AuthState, AuthAction } from './types';
+
+// Consumer imports from the module, not internal files
+import { AuthProvider, useAuth } from '@/features/auth';
+```
+
+3. **Configure path aliases** in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"],
+      "@/db/*": ["src/db/*"],
+      "@/lib/*": ["src/lib/*"]
+    }
+  }
+}
+```
+
+Mirror in your bundler config (Next.js, Vite, etc.) so runtime resolution matches TypeScript's.
+
+4. **`export type` for type-only exports** — prevents runtime import of type-only modules:
+
+```typescript
+export type { User, Post } from './types';
+export { createUser } from './user';
+```
+
+5. **`import type` for type-only imports:**
+
+```typescript
+import type { User } from './types';
+import { createUser } from './user';
+```
+
+Enable `verbatimModuleSyntax` in tsconfig to enforce this distinction.
+
+6. **Declaration files (.d.ts)** — provide types for JavaScript modules:
+
+```typescript
+// legacy-module.d.ts
+declare module 'legacy-module' {
+  export function doWork(input: string): number;
+  export interface Config {
+    verbose: boolean;
+  }
+}
+```
+
+7. **Namespace imports** for modules with many exports:
+
+```typescript
+import * as Schema from '@/db/schema';
+
+const user = Schema.users;
+const post = Schema.posts;
+```
+
+8. **Avoid circular imports** — if module A imports from B and B imports from A:
+   - Extract shared types into a separate module C
+   - Use `import type` when only types are needed (type imports are erased and do not cause runtime circularity)
+   - Restructure to unidirectional dependencies
+
+9. **Package entry points** — configure `exports` in `package.json` for library projects:
+
+```json
+{
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
+    "./utils": { "types": "./dist/utils.d.ts", "import": "./dist/utils.js" }
+  }
+}
+```
+
+## Details
+
+TypeScript modules follow the ES module standard. Each file with a top-level `import` or `export` is a module; files without them are scripts (global scope).
+
+**`verbatimModuleSyntax` (recommended):** Forces you to use `import type` for type-only imports and `export type` for type-only re-exports. This eliminates ambiguity about which imports are erased during compilation.
+
+**Barrel file trade-offs:**
+
+- Pros: Clean public API, consumers do not depend on internal file structure
+- Cons: Can defeat tree-shaking in some bundlers (import from barrel loads entire module), can create large import chains
+- Best practice: Use barrels at feature boundaries, not for every directory
+
+**Path aliases require bundler sync:** TypeScript's `paths` only affect type checking. The runtime module resolver (Node.js, Vite, webpack) must also be configured to resolve the same aliases.
+
+**`moduleResolution` options:**
+
+- `node` — traditional Node.js resolution (index.ts, package.json main)
+- `node16` / `nodenext` — Node.js ESM resolution (requires file extensions in imports)
+- `bundler` — modern bundler resolution (Vite, webpack, esbuild). Best choice for most frontend projects
+
+**Trade-offs:**
+
+- Barrel files improve DX but can hurt bundle size — profile with your bundler's analysis tool
+- Path aliases improve readability but add configuration overhead in every tool that processes imports
+- `verbatimModuleSyntax` catches real bugs but requires existing code to be updated with `import type`
+
+## Source
+
+https://typescriptlang.org/docs/handbook/modules.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/ts-module-patterns/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-module-patterns
+version: "1.0.0"
+description: Organize TypeScript code with ES modules, barrel exports, path aliases, and declaration files
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "tsconfig.json"
+  - "tsconfig.*.json"
+related_skills:
+  - ts-declaration-merging
+  - ts-config-patterns
+stack_signals:
+  - typescript
+keywords:
+  - ES-modules
+  - barrel-exports
+  - path-aliases
+  - declaration-files
+  - .d.ts
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/modules.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/ts-performance-patterns/SKILL.md

@@ -0,0 +1,158 @@
+# TypeScript Performance Patterns
+
+> Reduce TypeScript compilation time and type complexity with targeted optimizations
+
+## When to Use
+
+- TypeScript compilation or IDE type-checking is noticeably slow
+- Complex generic types cause "type instantiation is excessively deep" errors
+- Large monorepos need faster incremental builds
+- IDE autocompletion or hover information is sluggish
+
+## Instructions
+
+1. **Enable incremental compilation:**
+
+```json
+{
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": ".tsbuildinfo"
+  }
+}
+```
+
+2. **Enable `skipLibCheck`** to skip type-checking `.d.ts` files:
+
+```json
+{ "compilerOptions": { "skipLibCheck": true } }
+```
+
+This is the single biggest compilation speed improvement for most projects.
+
+3. **Use project references** to parallelize and cache builds:
+
+```json
+{ "references": [{ "path": "packages/a" }, { "path": "packages/b" }] }
+```
+
+Build with `tsc --build` for dependency-aware parallel compilation.
+
+4. **Simplify deep generic types** — break deeply nested generics into named intermediate types:
+
+```typescript
+// Slow: deeply nested inline generics
+type Bad = Map<string, Array<Promise<Result<Map<string, Set<number>>>>>>;
+
+// Fast: named intermediates
+type NumberSets = Map<string, Set<number>>;
+type ResultPromises = Array<Promise<Result<NumberSets>>>;
+type Good = Map<string, ResultPromises>;
+```
+
+5. **Avoid recursive types that expand exponentially:**
+
+```typescript
+// Can cause "type instantiation excessively deep" errors
+type DeepPartial<T> = {
+  [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+// Add a depth limiter
+type DeepPartial<T, D extends number = 5> = D extends 0
+  ? T
+  : { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K], Prev[D]> : T[K] };
+type Prev = [never, 0, 1, 2, 3, 4, 5];
+```
+
+6. **Use interfaces over type aliases** for object types — interfaces are more efficiently cached:
+
+```typescript
+// Faster — interface declaration is cached by name
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// Slower — type alias is re-evaluated each time it's referenced
+type User = { id: string; name: string; email: string };
+```
+
+7. **Limit union type size** — unions with >25 members can slow down type checking significantly. Group related types:
+
+```typescript
+// Slow: 50-member union
+type Event = EventA | EventB | EventC | ... | EventAX;
+
+// Faster: grouped unions
+type UserEvent = UserCreated | UserUpdated | UserDeleted;
+type OrderEvent = OrderPlaced | OrderShipped | OrderCancelled;
+type Event = UserEvent | OrderEvent;
+```
+
+8. **Use `isolatedModules`** for fast single-file transpilation with esbuild or swc:
+
+```json
+{ "compilerOptions": { "isolatedModules": true } }
+```
+
+9. **Exclude unnecessary files** from compilation:
+
+```json
+{
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.stories.ts"]
+}
+```
+
+10. **Profile the compiler** to find bottlenecks:
+
+```bash
+tsc --generateTrace ./trace
+# Open chrome://tracing and load the trace JSON
+```
+
+## Details
+
+TypeScript's type-checker is a constraint solver that runs at compile time. Complex types (deep generics, large unions, recursive mapped types) can cause exponential computation.
+
+**Common performance killers:**
+
+- Recursive conditional types without depth limits
+- Large template literal type Cartesian products
+- Hundreds of overloaded function signatures
+- Deeply nested `infer` chains
+- `@ts-ignore` on incorrect code (the checker still processes it)
+
+**Interface vs type alias performance:** Interfaces create named cached entries in the type checker. When the same interface is referenced multiple times, the checker reuses the cached result. Type aliases with intersection types (`A & B & C`) must be re-flattened at each use site.
+
+**`skipLibCheck` justification:** Third-party `.d.ts` files rarely change between builds, and their type errors are not actionable by your team. Skipping them saves 20-40% of compilation time on typical projects.
+
+**Project references trade-offs:**
+
+- Pros: parallel builds, cached compilation, explicit dependency graph
+- Cons: more config files, `composite: true` requirement, declaration files must be generated
+- Best for: monorepos with 3+ packages. Overkill for single-package projects
+
+**Measuring improvement:** Run `tsc --noEmit --diagnostics` to see check time, program size, and memory usage. Compare before and after optimizations.
+
+## Source
+
+https://typescriptlang.org/docs/handbook/performance.html
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/ts-performance-patterns/skill.yaml

@@ -0,0 +1,42 @@
+name: ts-performance-patterns
+version: "1.0.0"
+description: Reduce TypeScript compilation time and type complexity with targeted optimizations
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "tsconfig.json"
+  - "tsconfig.*.json"
+related_skills:
+  - ts-config-patterns
+  - ts-generics-pattern
+  - perf-tree-shaking
+  - perf-bundle-analysis
+  - perf-code-splitting
+  - perf-profiling-methodology
+stack_signals:
+  - typescript
+keywords:
+  - type-instantiation
+  - skipLibCheck
+  - isolatedModules
+  - type-complexity
+  - compilation-performance
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/performance.html
+state:
+  persistent: false
+  files: []
+depends_on: []