@harness-engineering/cli 1.23.1 → 1.24.0

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

@@ -0,0 +1,37 @@
+name: ts-module-patterns
+version: "1.0.0"
+description: Organize TypeScript code with ES modules, barrel exports, path aliases, and declaration files
+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/cursor/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/cursor/ts-performance-patterns/skill.yaml

@@ -0,0 +1,37 @@
+name: ts-performance-patterns
+version: "1.0.0"
+description: Reduce TypeScript compilation time and type complexity with targeted optimizations
+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
+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: []

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,38 @@
+name: ts-satisfies-operator
+version: "1.0.0"
+description: Validate objects against a type without widening using the satisfies keyword
+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: []