@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/ts-branded-types/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-branded-types
+version: "1.0.0"
+description: Prevent mixing semantically distinct primitives using branded opaque 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-discriminated-unions
+  - ts-type-guards
+  - ts-generics-pattern
+stack_signals:
+  - typescript
+keywords:
+  - branded-types
+  - opaque-types
+  - nominal-typing
+  - validation-boundaries
+  - type-safety
+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-class-patterns/SKILL.md

@@ -0,0 +1,238 @@
+# TypeScript Class Patterns
+
+> Use abstract classes, private fields, access modifiers, and implements vs extends correctly
+
+## When to Use
+
+- Modeling domain entities with encapsulation and inheritance
+- Defining abstract base classes with enforced method contracts
+- Choosing between `implements` (interface conformance) and `extends` (inheritance)
+- Using access modifiers and private fields for encapsulation
+
+## Instructions
+
+1. **Basic class with typed properties:**
+
+```typescript
+class User {
+  readonly id: string;
+  name: string;
+  private email: string;
+
+  constructor(id: string, name: string, email: string) {
+    this.id = id;
+    this.name = name;
+    this.email = email;
+  }
+
+  getEmail(): string {
+    return this.email;
+  }
+}
+```
+
+2. **Parameter properties** — shorthand for constructor assignment:
+
+```typescript
+class User {
+  constructor(
+    readonly id: string,
+    public name: string,
+    private email: string
+  ) {}
+}
+// Equivalent to the longer form above
+```
+
+3. **Access modifiers:**
+   - `public` (default) — accessible everywhere
+   - `private` — accessible only within the class (TypeScript-only enforcement)
+   - `protected` — accessible within the class and subclasses
+   - `#field` — true private (JavaScript runtime enforcement, not just TypeScript)
+
+```typescript
+class Account {
+  #balance: number; // True private — not accessible even via type assertions
+
+  constructor(initial: number) {
+    this.#balance = initial;
+  }
+
+  get balance(): number {
+    return this.#balance;
+  }
+}
+```
+
+4. **Abstract classes** — define contracts with partial implementations:
+
+```typescript
+abstract class Shape {
+  abstract area(): number;
+  abstract perimeter(): number;
+
+  describe(): string {
+    return `Area: ${this.area()}, Perimeter: ${this.perimeter()}`;
+  }
+}
+
+class Circle extends Shape {
+  constructor(private radius: number) {
+    super();
+  }
+
+  area(): number {
+    return Math.PI * this.radius ** 2;
+  }
+  perimeter(): number {
+    return 2 * Math.PI * this.radius;
+  }
+}
+```
+
+5. **`implements` for interface conformance:**
+
+```typescript
+interface Serializable {
+  serialize(): string;
+  deserialize(data: string): void;
+}
+
+class Config implements Serializable {
+  constructor(private data: Record<string, string>) {}
+
+  serialize(): string {
+    return JSON.stringify(this.data);
+  }
+  deserialize(data: string): void {
+    this.data = JSON.parse(data);
+  }
+}
+```
+
+6. **`extends` vs `implements`:**
+   - `extends` — single inheritance, inherits implementation
+   - `implements` — multiple interface conformance, no implementation inherited
+
+```typescript
+interface Loggable {
+  log(message: string): void;
+}
+interface Cacheable {
+  cache(): void;
+}
+
+class Service extends BaseService implements Loggable, Cacheable {
+  log(message: string): void {
+    /* ... */
+  }
+  cache(): void {
+    /* ... */
+  }
+}
+```
+
+7. **Static members:**
+
+```typescript
+class IdGenerator {
+  private static counter = 0;
+
+  static next(): string {
+    return `id_${++IdGenerator.counter}`;
+  }
+}
+```
+
+8. **Generic classes:**
+
+```typescript
+class Repository<T extends { id: string }> {
+  private items = new Map<string, T>();
+
+  save(item: T): void {
+    this.items.set(item.id, item);
+  }
+  find(id: string): T | undefined {
+    return this.items.get(id);
+  }
+  findAll(): T[] {
+    return [...this.items.values()];
+  }
+}
+
+const userRepo = new Repository<User>();
+```
+
+9. **Prefer composition over inheritance** when the relationship is "has-a" not "is-a":
+
+```typescript
+// Instead of: class UserService extends DatabaseService extends LoggingService
+class UserService {
+  constructor(
+    private db: DatabaseService,
+    private logger: LoggingService
+  ) {}
+}
+```
+
+## Details
+
+TypeScript classes compile to JavaScript classes (ES2015+) or constructor functions (ES5 target). They add type annotations, access modifiers, and abstract members on top of standard JavaScript class syntax.
+
+**`private` vs `#private`:**
+
+- `private` — TypeScript compile-time only. The property is still accessible at runtime via `(obj as any).field` or `obj['field']`
+- `#private` — JavaScript runtime enforcement. The property is truly inaccessible outside the class. Cannot be accessed even through reflection
+
+**Abstract classes vs interfaces:**
+
+- Abstract classes can contain implemented methods (shared logic) and abstract methods (contracts)
+- Interfaces contain only type signatures (no implementation)
+- A class can extend only one abstract class but implement many interfaces
+- Use abstract classes when you need shared behavior; use interfaces when you need only a contract
+
+**`override` keyword (TypeScript 4.3+):**
+
+```typescript
+class Animal {
+  move(): void {
+    /* ... */
+  }
+}
+
+class Dog extends Animal {
+  override move(): void {
+    /* ... */
+  } // Error if parent method does not exist
+}
+```
+
+Enable `noImplicitOverride` to require the `override` keyword on all overridden methods.
+
+**Trade-offs:**
+
+- Classes provide clear encapsulation boundaries — but can lead to deep inheritance hierarchies
+- Abstract classes enforce contracts AND share code — but restrict you to single inheritance
+- Parameter properties reduce boilerplate — but can be surprising to developers from other languages
+- `#private` fields are truly private — but cannot be accessed in tests, which some teams dislike
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/classes.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-class-patterns/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-class-patterns
+version: "1.0.0"
+description: Use abstract classes, private fields, access modifiers, and implements vs extends correctly
+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-decorator-patterns
+  - ts-generics-pattern
+  - gof-factory-method
+stack_signals:
+  - typescript
+keywords:
+  - abstract-classes
+  - private-fields
+  - access-modifiers
+  - implements
+  - extends
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/classes.html
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,142 @@
+# TypeScript Conditional Types
+
+> Use conditional types, infer, and distributive logic to derive types programmatically
+
+## When to Use
+
+- Deriving a type based on the shape of another type
+- Extracting nested types from generics (unwrapping Promises, extracting array elements)
+- Building type-level branching logic (if-then-else at the type level)
+- Creating utility types that adapt to their input
+
+## Instructions
+
+1. **Basic conditional type** — `T extends U ? TrueType : FalseType`:
+
+```typescript
+type IsString<T> = T extends string ? true : false;
+
+type A = IsString<'hello'>; // true
+type B = IsString<42>; // false
+```
+
+2. **Extract nested types with `infer`:**
+
+```typescript
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+type A = UnwrapPromise<Promise<string>>; // string
+type B = UnwrapPromise<number>; // number
+
+type ArrayElement<T> = T extends (infer E)[] ? E : never;
+
+type C = ArrayElement<string[]>; // string
+```
+
+3. **Recursive unwrapping:**
+
+```typescript
+type DeepUnwrap<T> = T extends Promise<infer U> ? DeepUnwrap<U> : T;
+
+type A = DeepUnwrap<Promise<Promise<string>>>; // string
+```
+
+4. **Function type extraction:**
+
+```typescript
+type Parameters<T> = T extends (...args: infer P) => any ? P : never;
+type ReturnType<T> = T extends (...args: any) => infer R ? R : never;
+
+type Params = Parameters<(a: string, b: number) => void>; // [string, number]
+```
+
+5. **Distributive conditional types** — when `T` is a union, the condition distributes over each member:
+
+```typescript
+type NonNullable<T> = T extends null | undefined ? never : T;
+
+type A = NonNullable<string | null | undefined>; // string
+// Distributes as: (string extends null ? never : string) | (null extends null ? never : null) | ...
+```
+
+6. **Prevent distribution** by wrapping in a tuple:
+
+```typescript
+type IsUnion<T> = [T] extends [T] ? false : true; // Does not distribute
+```
+
+7. **Constrain `infer` with `extends`:**
+
+```typescript
+type FirstString<T> = T extends [infer F extends string, ...any[]] ? F : never;
+
+type A = FirstString<['hello', 42]>; // 'hello'
+type B = FirstString<[42, 'hello']>; // never
+```
+
+8. **Combine with mapped types for powerful transformations:**
+
+```typescript
+type OptionalByKey<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+type User = { id: string; name: string; email: string };
+type CreateUser = OptionalByKey<User, 'id'>; // id is optional, rest required
+```
+
+9. **Chain conditional types** for multi-branch logic:
+
+```typescript
+type TypeName<T> = T extends string
+  ? 'string'
+  : T extends number
+    ? 'number'
+    : T extends boolean
+      ? 'boolean'
+      : T extends Function
+        ? 'function'
+        : 'object';
+```
+
+## Details
+
+Conditional types are TypeScript's mechanism for type-level computation. They enable types that depend on other types, analogous to ternary expressions at the value level.
+
+**Distribution behavior:** When a conditional type is applied to a naked type parameter that is a union, it distributes — the condition is applied to each union member separately, and the results form a new union. This is usually desirable but can be surprising.
+
+**`infer` keyword:** Only valid inside the `extends` clause of a conditional type. It declares a type variable that TypeScript infers from the structure being matched. You can use multiple `infer` keywords in one condition.
+
+**`never` in conditionals:** A conditional branch that returns `never` removes that member from a union (since `T | never = T`). This is the mechanism behind `Exclude`, `Extract`, and `NonNullable`.
+
+**Recursive conditional types:** TypeScript supports recursive conditional types (up to a depth limit). Use them for deep unwrapping, recursive object transformation, or path-based type extraction.
+
+**Trade-offs:**
+
+- Conditional types make the type system Turing-complete — but deeply nested conditionals slow down the compiler
+- Distributive behavior is implicit and can produce unexpected results with union inputs
+- `infer` can only capture types at specific structural positions — it cannot pattern-match arbitrary nested types
+
+**Common mistakes:**
+
+- Forgetting that `T extends U` checks assignability, not equality — `string extends string | number` is `true`
+- Not accounting for `never` input — `never extends anything` distributes to `never` (empty union)
+- Using `infer` outside of a conditional type's extends clause — it is not a standalone keyword
+
+## Source
+
+https://typescriptlang.org/docs/handbook/2/conditional-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-conditional-types/skill.yaml

@@ -0,0 +1,38 @@
+name: ts-conditional-types
+version: "1.0.0"
+description: Use conditional types, infer, and distributive logic to derive types programmatically
+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-utility-types
+stack_signals:
+  - typescript
+keywords:
+  - conditional-types
+  - infer
+  - distributive
+  - template-literal-types
+  - extends
+metadata:
+  author: community
+  upstream: typescriptlang.org/docs/handbook/2/conditional-types.html
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/ts-config-patterns/SKILL.md

@@ -0,0 +1,190 @@
+# TypeScript Config Patterns
+
+> Configure tsconfig with extends, project references, composite builds, and incremental compilation
+
+## When to Use
+
+- Setting up tsconfig.json for a new project
+- Organizing shared TypeScript configuration across a monorepo
+- Enabling project references for faster builds in multi-package repos
+- Troubleshooting TypeScript compilation issues
+
+## Instructions
+
+1. **Minimal modern tsconfig** for a Node.js/Next.js project:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+2. **Extend a shared base config:**
+
+```json
+// tsconfig.base.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  }
+}
+
+// packages/api/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"]
+}
+```
+
+3. **Project references** for monorepo builds:
+
+```json
+// tsconfig.json (root)
+{
+  "references": [
+    { "path": "packages/shared" },
+    { "path": "packages/api" },
+    { "path": "packages/web" }
+  ],
+  "files": []
+}
+
+// packages/shared/tsconfig.json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": ["src"]
+}
+
+// packages/api/tsconfig.json
+{
+  "references": [{ "path": "../shared" }],
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist"
+  }
+}
+```
+
+Build with: `tsc --build` (builds referenced projects in dependency order).
+
+4. **Incremental compilation** — cache type check results:
+
+```json
+{
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": ".tsbuildinfo"
+  }
+}
+```
+
+5. **Separate configs for different concerns:**
+
+```json
+// tsconfig.json — IDE and type checking (no emit)
+{
+  "compilerOptions": { "noEmit": true },
+  "include": ["src", "tests"]
+}
+
+// tsconfig.build.json — production build (emit, no tests)
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "noEmit": false, "outDir": "dist" },
+  "include": ["src"],
+  "exclude": ["**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+6. **Key options explained:**
+   - `target` — JavaScript version to emit. Use `ES2022` for Node 18+, `ES2021` for broader compat
+   - `module` — Module system. `ESNext` for bundler-based projects, `NodeNext` for Node.js packages
+   - `moduleResolution` — `bundler` for Vite/webpack/Next.js, `NodeNext` for Node.js libraries
+   - `isolatedModules` — required for esbuild/swc transpilation (one file at a time)
+   - `skipLibCheck` — skip type checking `.d.ts` files from dependencies. Almost always enable
+
+7. **Configure for testing:**
+
+```json
+// vitest needs jsdom types
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
+```
+
+## Details
+
+`tsconfig.json` controls both the TypeScript compiler and the language service (IDE features). Many projects use TypeScript only for type checking (`noEmit: true`) while a bundler (Vite, esbuild, Next.js) handles actual compilation.
+
+**`composite: true` requirements:**
+
+- `declaration: true` must be set
+- All input files must be matched by `include` or listed in `files`
+- `rootDir` defaults to the directory containing `tsconfig.json`
+- Enables `tsc --build` mode for dependency-aware compilation
+
+**`moduleResolution` choices:**
+
+- `bundler` — best for projects using Vite, webpack, esbuild, Next.js. Allows extensionless imports, `index.ts` resolution, and `package.json` exports
+- `NodeNext` / `Node16` — for pure Node.js packages. Requires `.js` extensions in imports (even for `.ts` files). Enforces ESM/CJS boundaries
+- `node` (legacy) — Node.js CommonJS resolution. Avoid for new projects
+
+**`paths` vs `baseUrl`:** `paths` requires `baseUrl` in older TypeScript versions but since TypeScript 5.0+, `paths` can be relative to the tsconfig directory without `baseUrl`.
+
+**Trade-offs:**
+
+- `skipLibCheck: true` speeds up compilation significantly — but hides type errors in `.d.ts` files from dependencies
+- `incremental: true` speeds up subsequent builds — but creates a `.tsbuildinfo` file that should be gitignored
+- Project references enable parallel builds — but add complexity to the monorepo configuration
+- `isolatedModules` is required for fast transpilers — but prevents `const enum` and namespace merging across files
+
+## Source
+
+https://typescriptlang.org/tsconfig
+
+## 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.