@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/ts-testing-types/SKILL.md

@@ -0,0 +1,166 @@
+# TypeScript Testing Types
+
+> Test TypeScript types at compile time using expect-type, tsd, and vitest type matchers
+
+## When to Use
+
+- Verifying that utility types produce the expected output types
+- Testing that generic functions infer types correctly
+- Ensuring library public APIs maintain correct type signatures
+- Catching type regressions in CI without runtime tests
+
+## Instructions
+
+1. **Use `expectTypeOf` from vitest** (built-in, no extra dependencies):
+
+```typescript
+import { expectTypeOf, test } from 'vitest';
+
+test('User type has correct shape', () => {
+  expectTypeOf<User>().toMatchTypeOf<{
+    id: string;
+    name: string;
+    email: string;
+  }>();
+});
+```
+
+2. **Test function return types:**
+
+```typescript
+test('createUser returns User', () => {
+  expectTypeOf(createUser).returns.toMatchTypeOf<User>();
+  expectTypeOf(createUser).parameters.toEqualTypeOf<[name: string, email: string]>();
+});
+```
+
+3. **Test generic inference:**
+
+```typescript
+test('identity preserves literal types', () => {
+  const result = identity('hello');
+  expectTypeOf(result).toEqualTypeOf<'hello'>();
+});
+```
+
+4. **Verify types are NOT assignable:**
+
+```typescript
+test('UserId and PostId are not interchangeable', () => {
+  expectTypeOf<UserId>().not.toEqualTypeOf<PostId>();
+  expectTypeOf<UserId>().not.toMatchTypeOf<PostId>();
+});
+```
+
+5. **Use `expect-type` library** for standalone type tests:
+
+```typescript
+import { expectTypeOf } from 'expect-type';
+
+// In a .test-d.ts file or regular test file
+expectTypeOf<Pick<User, 'id' | 'name'>>().toEqualTypeOf<{
+  id: string;
+  name: string;
+}>();
+
+expectTypeOf<Partial<User>>().toMatchTypeOf<{ id?: string }>();
+```
+
+6. **Use `tsd`** for declaration file testing:
+
+```typescript
+// test-d.ts
+import { expectType, expectError } from 'tsd';
+import { createUser } from './index';
+
+expectType<User>(createUser('Alice', 'alice@test.com'));
+expectError(createUser(123)); // Should fail with number input
+```
+
+Run with `npx tsd` in package.json.
+
+7. **Test conditional types:**
+
+```typescript
+test('UnwrapPromise extracts inner type', () => {
+  expectTypeOf<UnwrapPromise<Promise<string>>>().toEqualTypeOf<string>();
+  expectTypeOf<UnwrapPromise<Promise<Promise<number>>>>().toEqualTypeOf<number>();
+  expectTypeOf<UnwrapPromise<string>>().toEqualTypeOf<string>();
+});
+```
+
+8. **Test mapped types:**
+
+```typescript
+test('Nullable adds null to all properties', () => {
+  type Input = { name: string; age: number };
+  type Expected = { name: string | null; age: number | null };
+  expectTypeOf<Nullable<Input>>().toEqualTypeOf<Expected>();
+});
+```
+
+9. **Compile-time only assertions** (no runtime, no test runner):
+
+```typescript
+// types.test.ts — checked by tsc, not executed
+type Assert<T extends true> = T;
+type IsEqual<A, B> = [A] extends [B] ? ([B] extends [A] ? true : false) : false;
+
+type _test1 = Assert<IsEqual<ReturnType<typeof getUser>, Promise<User>>>;
+type _test2 = Assert<IsEqual<Parameters<typeof createUser>, [string, string]>>;
+```
+
+## Details
+
+Type tests verify that your type-level code (generics, utility types, conditional types) produces the expected types. They catch regressions that runtime tests cannot — a function might work correctly at runtime but accept the wrong types due to an overly permissive generic.
+
+**`toEqualTypeOf` vs `toMatchTypeOf`:**
+
+- `toEqualTypeOf` — exact match. `{ a: string }` does NOT equal `{ a: string; b?: number }`
+- `toMatchTypeOf` — structural compatibility. `{ a: string; b: number }` MATCHES `{ a: string }`
+
+**Tool comparison:**
+
+- **Vitest `expectTypeOf`** — integrated into vitest, runs alongside runtime tests, best for projects already using vitest
+- **`expect-type`** — standalone library, works with any test runner, same API as vitest's built-in
+- **`tsd`** — designed for library authors testing .d.ts files, uses a different assertion API
+
+**When to test types:**
+
+- Utility types that transform other types (DeepPartial, NonNullable variants)
+- Generic functions with complex inference
+- Public API surfaces of libraries
+- Discriminated union handlers (ensure exhaustiveness)
+
+**When NOT to test types:**
+
+- Simple type annotations (TypeScript already checks these)
+- One-off types used in a single file
+- Types that mirror a runtime test's assertions
+
+**Trade-offs:**
+
+- Type tests add maintenance overhead — but catch regressions that runtime tests miss
+- `expectTypeOf` assertions run at compile time, not runtime — test files must be type-checked by tsc
+- Complex type assertions can produce cryptic error messages
+- Type tests do not verify runtime behavior — always pair with runtime tests for critical paths
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/types-from-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/cursor/ts-testing-types/skill.yaml

@@ -0,0 +1,39 @@
+name: ts-testing-types
+version: "1.0.0"
+description: Test TypeScript types at compile time using expect-type, tsd, and vitest type matchers
+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:
+  - test-unit-patterns
+  - ts-generics-pattern
+  - ts-utility-types
+stack_signals:
+  - typescript
+keywords:
+  - expect-type
+  - tsd
+  - type-testing
+  - compile-time-tests
+  - vitest-type-matchers
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/types-from-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ts-type-guards/SKILL.md

@@ -0,0 +1,168 @@
+# TypeScript Type Guards
+
+> Narrow union types safely using type guards, assertion functions, and control flow
+
+## When to Use
+
+- Narrowing union types to access type-specific properties
+- Validating unknown data from APIs or user input
+- Replacing unsafe type assertions (`as`) with safe runtime checks
+- Creating reusable narrowing functions for domain types
+
+## Instructions
+
+1. **`typeof` guard** for primitives:
+
+```typescript
+function format(value: string | number): string {
+  if (typeof value === 'string') {
+    return value.toUpperCase(); // Narrowed to string
+  }
+  return value.toFixed(2); // Narrowed to number
+}
+```
+
+2. **`instanceof` guard** for class instances:
+
+```typescript
+function handleError(error: Error | string): string {
+  if (error instanceof Error) {
+    return error.message; // Narrowed to Error
+  }
+  return error; // Narrowed to string
+}
+```
+
+3. **Custom type guard** with `is` predicate:
+
+```typescript
+interface Cat {
+  meow(): void;
+}
+interface Dog {
+  bark(): void;
+}
+
+function isCat(animal: Cat | Dog): animal is Cat {
+  return 'meow' in animal;
+}
+
+function interact(animal: Cat | Dog) {
+  if (isCat(animal)) {
+    animal.meow(); // Narrowed to Cat
+  } else {
+    animal.bark(); // Narrowed to Dog
+  }
+}
+```
+
+4. **Narrowing with `in` operator:**
+
+```typescript
+type ApiResponse = { status: 'success'; data: User } | { status: 'error'; message: string };
+
+function handle(response: ApiResponse) {
+  if ('data' in response) {
+    console.log(response.data); // Narrowed to success variant
+  }
+}
+```
+
+5. **Assertion function** — narrows or throws:
+
+```typescript
+function assertDefined<T>(value: T | null | undefined, name: string): asserts value is T {
+  if (value == null) {
+    throw new Error(`Expected ${name} to be defined`);
+  }
+}
+
+function process(user: User | null) {
+  assertDefined(user, 'user');
+  // user is narrowed to User after this line
+  console.log(user.name);
+}
+```
+
+6. **Narrow `unknown` values** safely:
+
+```typescript
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isUser(value: unknown): value is User {
+  return isRecord(value) && typeof value.id === 'string' && typeof value.email === 'string';
+}
+```
+
+7. **Array filtering with type guards:**
+
+```typescript
+const items: (string | null)[] = ['a', null, 'b', null, 'c'];
+
+// Without type guard: (string | null)[]
+const filtered = items.filter((x) => x !== null);
+
+// With type guard: string[]
+const filtered = items.filter((x): x is string => x !== null);
+```
+
+8. **Discriminated union narrowing:**
+
+```typescript
+type Shape = { kind: 'circle'; radius: number } | { kind: 'rect'; width: number; height: number };
+
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case 'circle':
+      return Math.PI * shape.radius ** 2;
+    case 'rect':
+      return shape.width * shape.height;
+  }
+}
+```
+
+## Details
+
+Type guards are runtime checks that TypeScript uses to narrow types in subsequent code. They bridge the gap between TypeScript's static type system and JavaScript's dynamic runtime.
+
+**Control flow analysis:** TypeScript tracks type narrowing through `if/else`, `switch`, `return`, `throw`, and assignment. After a type guard condition, the type is narrowed in the true branch and the complement is narrowed in the else branch.
+
+**`is` predicates vs boolean returns:** A function returning `boolean` does not narrow types at the call site. A function returning `x is Type` does. The `is` predicate is a promise to the compiler — if you return `true`, the value IS that type.
+
+**Assertion functions** (`asserts x is T`) narrow the type AFTER the function call returns. If the assertion fails, the function must throw. This is useful for precondition checks at the top of functions.
+
+**`asserts` vs `is`:**
+
+- `is` — used in conditions (`if`, `filter`). Returns boolean.
+- `asserts` — used as a statement. Throws on failure. Narrows for subsequent code.
+
+**Truthiness narrowing:** TypeScript narrows `if (value)` to exclude `null`, `undefined`, `0`, `''`, and `false`. This is convenient but can exclude valid falsy values — use explicit `!= null` when `0` or `''` are valid.
+
+**Trade-offs:**
+
+- Custom type guards with `is` put the burden of correctness on the developer — an incorrect guard silently misnarrows
+- `instanceof` does not work across iframes, realms, or serialized objects
+- Assertion functions cannot be used in expression position — they must be standalone statements
+- Deep narrowing of nested objects requires multiple guard calls or a comprehensive validation library like Zod
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/narrowing.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/cursor/ts-type-guards/skill.yaml

@@ -0,0 +1,40 @@
+name: ts-type-guards
+version: "1.0.0"
+description: Narrow union types safely using type guards, assertion functions, and control flow
+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-discriminated-unions
+  - ts-branded-types
+  - ts-generics-pattern
+stack_signals:
+  - typescript
+keywords:
+  - type-guards
+  - narrowing
+  - is-predicate
+  - typeof
+  - instanceof
+  - assertion-functions
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/narrowing.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ts-utility-types/SKILL.md

@@ -0,0 +1,119 @@
+# TypeScript Utility Types
+
+> Apply built-in TypeScript utility types to transform and compose types without redundancy
+
+## When to Use
+
+- You need a variant of an existing type with some properties optional, required, or removed
+- You want to derive a type from a function's return value or parameter list without duplicating it
+- You need to build a lookup map type from a union of keys
+- You want to filter a union type to include or exclude specific members
+- You are building form types, API response shapes, or partial update payloads
+
+## Instructions
+
+1. Use `Partial<T>` for optional-update payloads where every field is optional.
+2. Use `Required<T>` to make every optional field mandatory (opposite of Partial).
+3. Use `Pick<T, K>` to create a type with only the listed keys from T.
+4. Use `Omit<T, K>` to create a type with all keys except the listed ones.
+5. Use `Record<K, V>` to define a mapping type — prefer over index signatures when keys are known.
+6. Use `Exclude<T, U>` to remove union members assignable to U from T.
+7. Use `Extract<T, U>` to keep only union members assignable to U.
+8. Use `ReturnType<typeof fn>` to derive the return type of a function without manually declaring it.
+9. Use `Parameters<typeof fn>` to derive the parameter tuple of a function.
+10. Chain utility types when needed: `Partial<Pick<User, 'name' | 'email'>>`.
+
+```typescript
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: 'admin' | 'viewer' | 'editor';
+  createdAt: Date;
+}
+
+// Partial update payload — all fields optional
+type UserUpdate = Partial<Omit<User, 'id' | 'createdAt'>>;
+
+// Public profile — only safe fields
+type PublicUser = Pick<User, 'id' | 'name' | 'role'>;
+
+// Role lookup map
+type RoleConfig = Record<User['role'], { canWrite: boolean; canDelete: boolean }>;
+
+// Exclude admin from public-facing role type
+type PublicRole = Exclude<User['role'], 'admin'>; // 'viewer' | 'editor'
+
+// Infer return type without coupling to implementation
+async function fetchUser(id: string): Promise<User> {
+  /* ... */ return {} as User;
+}
+type FetchUserResult = Awaited<ReturnType<typeof fetchUser>>; // User
+
+// Infer parameters for wrapping/mocking
+type FetchUserParams = Parameters<typeof fetchUser>; // [id: string]
+```
+
+## Details
+
+All utility types are implemented as generic conditional or mapped types in TypeScript's standard library (`lib.es5.d.ts`). Understanding their implementation helps you build custom variants when the built-ins don't cover your case.
+
+**Implementation anatomy**
+
+```typescript
+// Partial<T> implementation
+type Partial<T> = { [P in keyof T]?: T[P] };
+
+// Pick<T, K> implementation
+type Pick<T, K extends keyof T> = { [P in K]: T[P] };
+
+// Exclude<T, U> implementation
+type Exclude<T, U> = T extends U ? never : T;
+
+// ReturnType<T> implementation
+type ReturnType<T extends (...args: any) => any> = T extends (...args: any) => infer R ? R : any;
+```
+
+**`Omit` vs `Exclude`**
+
+`Omit<T, K>` operates on object types and removes properties. `Exclude<T, U>` operates on union types and removes members. They are not interchangeable.
+
+**`Record` vs index signatures**
+
+`Record<string, V>` and `{ [key: string]: V }` are equivalent for most purposes, but `Record<K, V>` with a union K creates a required entry for each union member — the index signature does not.
+
+**Composing utility types**
+
+Utility types compose via nesting. Deep transformations may require recursive types (TypeScript 4.1+) or a custom mapped type. For deeply partial types, the standard library's `Partial` only goes one level deep.
+
+**`NonNullable<T>`**
+
+Removes `null` and `undefined` from a type. Equivalent to `Exclude<T, null | undefined>`. Useful after null-safety guards.
+
+**`ConstructorParameters<T>` and `InstanceType<T>`**
+
+Less common but useful for class-based code: `ConstructorParameters` extracts the constructor's args, `InstanceType` extracts what `new T()` produces.
+
+**When to write custom utilities instead**
+
+When none of the built-ins express your transformation, write a mapped or conditional type. The built-ins are a starting point, not a ceiling.
+
+## Source
+
+https://typescriptlang.org/docs/handbook/utility-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/cursor/ts-utility-types/skill.yaml

@@ -0,0 +1,44 @@
+name: ts-utility-types
+version: "1.0.0"
+description: Apply built-in TypeScript utility types to transform and compose types without redundancy
+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-mapped-types
+  - ts-conditional-types
+stack_signals:
+  - typescript
+keywords:
+  - Partial
+  - Required
+  - Pick
+  - Omit
+  - Record
+  - Exclude
+  - Extract
+  - ReturnType
+  - Parameters
+  - utility-types
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/utility-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []