@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/cursor/ts-satisfies-operator/SKILL.md

@@ -0,0 +1,151 @@
+# TypeScript Satisfies Operator
+
+> Validate objects against a type without widening using the satisfies keyword
+
+## When to Use
+
+- Validating configuration objects while preserving literal types
+- Checking that a value conforms to a type without losing specific type information
+- Ensuring exhaustive key coverage in record-like objects
+- Replacing `as const` + type annotation patterns with a cleaner alternative
+
+## Instructions
+
+1. **Basic usage** — validate without widening:
+
+```typescript
+type Color = 'red' | 'green' | 'blue';
+type Colors = Record<string, Color>;
+
+// With type annotation — loses specific key information
+const colors: Colors = { primary: 'red', secondary: 'blue' };
+colors.tertiary; // No error — any string key is valid
+
+// With satisfies — preserves exact keys AND validates values
+const colors = {
+  primary: 'red',
+  secondary: 'blue',
+} satisfies Colors;
+
+colors.primary; // Type: 'red' (not just Color)
+colors.tertiary; // Error: property does not exist
+```
+
+2. **Configuration objects** — validate shape while keeping literal types:
+
+```typescript
+type Route = {
+  path: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+};
+
+const routes = {
+  getUser: { path: '/users/:id', method: 'GET' },
+  createUser: { path: '/users', method: 'POST' },
+} satisfies Record<string, Route>;
+
+// routes.getUser.method is 'GET' (literal), not 'GET' | 'POST' | 'PUT' | 'DELETE'
+```
+
+3. **Combine with `as const`** for full immutability:
+
+```typescript
+const config = {
+  port: 3000,
+  host: 'localhost',
+  features: ['auth', 'logging'],
+} as const satisfies {
+  port: number;
+  host: string;
+  features: readonly string[];
+};
+
+// config.port is 3000 (literal), config.features is readonly ['auth', 'logging']
+```
+
+4. **Exhaustive key checking** on enum-keyed objects:
+
+```typescript
+type Status = 'draft' | 'published' | 'archived';
+
+const statusLabels = {
+  draft: 'Draft',
+  published: 'Published',
+  archived: 'Archived',
+} satisfies Record<Status, string>;
+// Error if any status is missing
+```
+
+5. **Validate callback shapes** without losing return type information:
+
+```typescript
+type Handler = (req: Request) => Response | Promise<Response>;
+
+const handlers = {
+  home: (req) => new Response('Hello'),
+  api: async (req) => Response.json({ ok: true }),
+} satisfies Record<string, Handler>;
+```
+
+6. **Narrow union types in objects:**
+
+```typescript
+type Config = {
+  mode: 'development' | 'production';
+  debug: boolean;
+};
+
+const devConfig = {
+  mode: 'development',
+  debug: true,
+} satisfies Config;
+
+// devConfig.mode is 'development' (literal), not 'development' | 'production'
+```
+
+## Details
+
+The `satisfies` operator (TypeScript 4.9+) validates that an expression matches a type without changing the inferred type of the expression. This solves a long-standing tension in TypeScript between type validation and type inference.
+
+**`satisfies` vs type annotation:**
+
+- `const x: Type = value` — validates AND widens the type to `Type`. The specific value types are lost.
+- `const x = value satisfies Type` — validates against `Type` but infers the type from `value`. Literal types, specific keys, and narrower unions are preserved.
+
+**`satisfies` vs `as const`:**
+
+- `as const` makes everything readonly and literal but does not validate against a type
+- `satisfies` validates against a type but does not make values readonly
+- `as const satisfies Type` does both — readonly, literal, and validated
+
+**When to use which:**
+
+- Use `: Type` when you want to enforce a type contract and do not need literals (function parameters, class properties)
+- Use `satisfies Type` when you want validation AND literal preservation (config objects, route tables, enum maps)
+- Use `as const satisfies Type` when you need immutability AND validation
+
+**Trade-offs:**
+
+- `satisfies` is less familiar to many developers — use it consistently and explain in code review
+- Error messages from `satisfies` point to the mismatched property but can be verbose for complex types
+- `satisfies` cannot be used with variable declarations that need explicit types for external consumption (exported API surfaces)
+
+## Source
+
+https://typescriptlang.org/docs/handbook/release-notes/typescript-4-9.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-satisfies-operator/skill.yaml

@@ -0,0 +1,39 @@
+name: ts-satisfies-operator
+version: "1.0.0"
+description: Validate objects against a type without widening using the satisfies keyword
+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-type-guards
+  - ts-discriminated-unions
+  - ts-utility-types
+stack_signals:
+  - typescript
+keywords:
+  - satisfies
+  - type-checking
+  - widening
+  - object-literal
+  - validation
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/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/cursor/ts-strict-mode/skill.yaml

@@ -0,0 +1,39 @@
+name: ts-strict-mode
+version: "1.0.0"
+description: Enable and satisfy strict TypeScript checks including strictNullChecks and exactOptionalPropertyTypes
+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-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/cursor/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/cursor/ts-template-literal-types/skill.yaml

@@ -0,0 +1,39 @@
+name: ts-template-literal-types
+version: "1.0.0"
+description: Construct precise string types using template literal syntax and string manipulation types
+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-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: []