@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/gemini-cli/ts-strict-mode/SKILL.md

@@ -0,0 +1,167 @@
+# TypeScript Strict Mode
+
+> Enable and satisfy strict TypeScript checks including strictNullChecks and exactOptionalPropertyTypes
+
+## When to Use
+
+- Starting a new TypeScript project (always enable strict mode from day one)
+- Migrating an existing project to stricter type checking
+- Debugging type errors caused by strict flags
+- Deciding which individual strict flags to enable during incremental adoption
+
+## Instructions
+
+1. **Enable `strict: true`** in `tsconfig.json` — this activates all strict flags at once:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+2. **What `strict: true` enables:**
+   - `strictNullChecks` — `null` and `undefined` are not assignable to other types
+   - `strictFunctionTypes` — function parameter types are checked contravariantly
+   - `strictBindCallApply` — `bind`, `call`, `apply` are fully typed
+   - `strictPropertyInitialization` — class properties must be initialized
+   - `noImplicitAny` — untyped variables/parameters are errors, not `any`
+   - `noImplicitThis` — `this` must have a type in function bodies
+   - `alwaysStrict` — emits `"use strict"` in every file
+   - `useUnknownInCatchVariables` — catch variables are `unknown`, not `any`
+
+3. **Handle `strictNullChecks`** — the most impactful flag. Check for null before accessing:
+
+```typescript
+function getUser(id: string): User | null {
+  /* ... */
+}
+
+const user = getUser('123');
+// user.name; // Error: Object is possibly 'null'
+if (user) {
+  user.name; // OK — narrowed to User
+}
+```
+
+4. **Handle `noImplicitAny`** — add explicit types where inference fails:
+
+```typescript
+// Error: Parameter 'item' implicitly has an 'any' type
+function process(item) {
+  /* ... */
+}
+
+// Fixed
+function process(item: unknown) {
+  /* ... */
+}
+```
+
+5. **Handle `strictPropertyInitialization`** — initialize class properties:
+
+```typescript
+class Service {
+  // Error: Property 'db' has no initializer
+  private db: Database;
+
+  // Fix 1: Initialize in constructor
+  constructor(db: Database) {
+    this.db = db;
+  }
+
+  // Fix 2: Definite assignment assertion (use sparingly)
+  private db!: Database;
+}
+```
+
+6. **Handle `useUnknownInCatchVariables`:**
+
+```typescript
+try {
+  await fetchData();
+} catch (error) {
+  // error is 'unknown', not 'any'
+  if (error instanceof Error) {
+    console.log(error.message);
+  }
+}
+```
+
+7. **Additional strict flags beyond `strict: true`:**
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noPropertyAccessFromIndexSignature": true
+  }
+}
+```
+
+8. **`noUncheckedIndexedAccess`** — index signatures include `undefined`:
+
+```typescript
+const map: Record<string, string> = { a: 'hello' };
+// Without flag: map['b'] is string
+// With flag: map['b'] is string | undefined
+```
+
+9. **Incremental strict adoption** — enable flags one at a time:
+
+```json
+{
+  "compilerOptions": {
+    "strict": false,
+    "strictNullChecks": true,
+    "noImplicitAny": true
+  }
+}
+```
+
+Fix errors per flag before enabling the next.
+
+## Details
+
+Strict mode catches entire categories of bugs at compile time: null dereferences, implicit `any` types, uninitialized properties, and unsafe function calls. The upfront cost of fixing strict errors pays back quickly in reduced runtime bugs.
+
+**`noUncheckedIndexedAccess`** is not included in `strict: true` but is one of the most valuable additional flags. It forces you to handle the case where an array index or object key might not exist, preventing `undefined is not a function` errors.
+
+**`exactOptionalPropertyTypes`** distinguishes between "property is missing" and "property is `undefined`". With this flag, `{ name?: string }` means the property may be absent, but if present it must be a `string` (not `undefined`).
+
+**Strict migration strategy:**
+
+1. Enable `strict: true` and count the errors
+2. If manageable (<100), fix them all at once
+3. If large (>100), disable `strict` and enable flags individually: `noImplicitAny` first (most errors), then `strictNullChecks`, then the rest
+4. Use `// @ts-expect-error` temporarily for errors you cannot fix immediately — track them with a lint rule
+
+**Trade-offs:**
+
+- Strict mode increases type annotation verbosity — but reduces debugging time
+- `strictNullChecks` causes the most migration pain — but prevents the most common runtime error (null dereference)
+- `noUncheckedIndexedAccess` adds `| undefined` to every index access — use non-null assertion (`!`) or destructuring with defaults for known-safe accesses
+- Third-party libraries with loose types can produce cascading strict errors — use declaration merging to fix them locally
+
+## Source
+
+https://typescriptlang.org/tsconfig#strict
+
+## 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-strict-mode/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-strict-mode
+version: "1.0.0"
+description: Enable and satisfy strict TypeScript checks including strictNullChecks and exactOptionalPropertyTypes
+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-type-guards
+  - ts-error-handling-types
+stack_signals:
+  - typescript
+keywords:
+  - strict-mode
+  - strictNullChecks
+  - noUncheckedIndexedAccess
+  - exactOptionalPropertyTypes
+  - strict-flags
+metadata:
+  author: community
+  upstream: typescriptlang.org/tsconfig#strict
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,146 @@
+# TypeScript Template Literal Types
+
+> Construct precise string types using template literal syntax and string manipulation types
+
+## When to Use
+
+- Creating type-safe string patterns (event names, CSS values, API routes)
+- Generating getter/setter method names from property names
+- Building type-safe routing or event systems
+- Manipulating string literal types with Capitalize, Uppercase, Lowercase
+
+## Instructions
+
+1. **Basic template literal type:**
+
+```typescript
+type EventName = `on${Capitalize<'click' | 'hover' | 'focus'>}`;
+// 'onClick' | 'onHover' | 'onFocus'
+```
+
+2. **Combine with union types** — distributes across all combinations:
+
+```typescript
+type Color = 'red' | 'blue' | 'green';
+type Size = 'sm' | 'md' | 'lg';
+type ClassName = `${Color}-${Size}`;
+// 'red-sm' | 'red-md' | 'red-lg' | 'blue-sm' | 'blue-md' | ...
+```
+
+3. **Type-safe event emitters:**
+
+```typescript
+type Events = {
+  click: { x: number; y: number };
+  change: { value: string };
+  submit: { data: FormData };
+};
+
+type OnEvent = `on${Capitalize<keyof Events>}`;
+// 'onClick' | 'onChange' | 'onSubmit'
+```
+
+4. **String manipulation utility types:**
+
+```typescript
+type Upper = Uppercase<'hello'>; // 'HELLO'
+type Lower = Lowercase<'HELLO'>; // 'hello'
+type Cap = Capitalize<'hello'>; // 'Hello'
+type Uncap = Uncapitalize<'Hello'>; // 'hello'
+```
+
+5. **Generate property names from a type:**
+
+```typescript
+type Getters<T> = {
+  [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K];
+};
+
+type Setters<T> = {
+  [K in keyof T as `set${Capitalize<string & K>}`]: (value: T[K]) => void;
+};
+
+type UserAccessors = Getters<{ name: string; age: number }>;
+// { getName: () => string; getAge: () => number }
+```
+
+6. **Pattern matching with `infer`:**
+
+```typescript
+type ExtractRouteParams<T extends string> = T extends `${string}:${infer Param}/${infer Rest}`
+  ? Param | ExtractRouteParams<`/${Rest}`>
+  : T extends `${string}:${infer Param}`
+    ? Param
+    : never;
+
+type Params = ExtractRouteParams<'/users/:userId/posts/:postId'>;
+// 'userId' | 'postId'
+```
+
+7. **Type-safe CSS values:**
+
+```typescript
+type CSSUnit = 'px' | 'em' | 'rem' | '%' | 'vh' | 'vw';
+type CSSLength = `${number}${CSSUnit}`;
+
+function setWidth(width: CSSLength): void {
+  /* ... */
+}
+
+setWidth('100px'); // OK
+setWidth('2.5rem'); // OK
+setWidth('100'); // Error: not assignable to CSSLength
+```
+
+8. **Dot-notation path types:**
+
+```typescript
+type DotPath<T, Prefix extends string = ''> = {
+  [K in keyof T & string]: T[K] extends object ? DotPath<T[K], `${Prefix}${K}.`> : `${Prefix}${K}`;
+}[keyof T & string];
+
+type Paths = DotPath<{ user: { name: string; address: { city: string } } }>;
+// 'user.name' | 'user.address.city'
+```
+
+## Details
+
+Template literal types (TypeScript 4.1+) allow string types to be composed from other string literals, unions, and type-level transformations. They are the string equivalent of mapped types — they generate new types by iterating over string combinations.
+
+**Distribution:** When a template literal contains union types, it produces the Cartesian product. `\`${A | B}-${C | D}\``produces`'A-C' | 'A-D' | 'B-C' | 'B-D'`.
+
+**Intrinsic string manipulation types:** `Uppercase<S>`, `Lowercase<S>`, `Capitalize<S>`, `Uncapitalize<S>` are built-in compiler intrinsics — they work on any string literal type.
+
+**Pattern matching:** Template literal types with `infer` can extract parts of string types. This enables parsing route parameters, CSS values, and other structured strings at the type level.
+
+**Performance considerations:**
+
+- Large Cartesian products slow the compiler. `\`${100 values}-${100 values}\`` creates 10,000 types
+- Recursive template literal types have a depth limit. Keep recursion shallow
+- Avoid template literals in hot type positions (deeply nested generics)
+
+**Trade-offs:**
+
+- Precise string typing catches typos at compile time — but generates verbose union types in IDE tooltips
+- Route parameter extraction is elegant — but error messages when a route does not match are cryptic
+- Template literals distribute over unions automatically — this is powerful but can produce unexpectedly large types
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/template-literal-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-template-literal-types/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-template-literal-types
+version: "1.0.0"
+description: Construct precise string types using template literal syntax and string manipulation types
+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-conditional-types
+  - ts-mapped-types
+  - ts-discriminated-unions
+stack_signals:
+  - typescript
+keywords:
+  - template-literal-types
+  - Capitalize
+  - Uppercase
+  - string-manipulation
+  - key-remapping
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/template-literal-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/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/gemini-cli/ts-testing-types/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-testing-types
+version: "1.0.0"
+description: Test TypeScript types at compile time using expect-type, tsd, and vitest type matchers
+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: []