@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/angular-performance-patterns/SKILL.md

@@ -0,0 +1,141 @@
+# Angular Performance Patterns
+
+> Optimize Angular rendering with OnPush change detection, trackBy, virtual scrolling, deferrable views, and signals for zoneless-ready apps
+
+## When to Use
+
+- A list or table is causing visible jank during scrolling or filtering
+- The Angular DevTools profiler shows excessive change detection cycles
+- A component tree is deep and updates are propagating to many unrelated components
+- Rendering thousands of items in a `*ngFor` causes memory or scroll performance issues
+- Heavy components below the fold are delaying time-to-interactive
+
+## Instructions
+
+1. Set `changeDetection: ChangeDetectionStrategy.OnPush` on every component. With `OnPush`, Angular only checks a component when its input references change, an `async` pipe emits, or a signal updates — not on every browser event.
+2. Use `trackBy` with `*ngFor` to prevent Angular from destroying and re-creating DOM nodes when the array reference changes: `*ngFor="let item of items; trackBy: trackById"`. The track function should return a stable unique identifier (e.g., the item's ID).
+3. Use `@angular/cdk/scrolling` `CdkVirtualScrollViewport` for lists with more than ~100 items. Virtual scrolling renders only the visible items, keeping DOM size constant regardless of data size.
+4. Use `@defer (on viewport)` for components below the fold — they won't load until the user scrolls to them, reducing initial bundle execution time.
+5. Move expensive pure calculations into `computed()` signals or pure pipes — both memoize their results and only recompute when dependencies change.
+6. Avoid function calls in templates (`{{ computeTotal() }}`) — they execute on every change detection cycle. Replace with `computed()` signals or `@Input()` derived values.
+7. Avoid `setTimeout`/`setInterval` without wrapping in `NgZone.runOutsideAngular()` for non-UI timers — they trigger change detection on every tick.
+8. Adopt signals for local component state to prepare for zoneless change detection (`provideExperimentalZonelessChangeDetection()` in Angular 18+).
+
+```typescript
+// OnPush + trackBy
+@Component({
+  selector: 'app-product-list',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <app-product-card *ngFor="let product of products(); trackBy: trackById" [product]="product" />
+  `,
+})
+export class ProductListComponent {
+  products = input.required<Product[]>();
+  trackById = (_: number, item: Product) => item.id;
+}
+```
+
+```typescript
+// Virtual scrolling with CDK
+import { ScrollingModule, CdkVirtualScrollViewport } from '@angular/cdk/scrolling';
+
+@Component({
+  imports: [ScrollingModule],
+  template: `
+    <cdk-virtual-scroll-viewport itemSize="72" style="height: 600px">
+      <div
+        *cdkVirtualFor="let item of items; trackBy: trackById"
+        class="list-item"
+        style="height: 72px"
+      >
+        {{ item.name }}
+      </div>
+    </cdk-virtual-scroll-viewport>
+  `,
+})
+export class VirtualListComponent {
+  items = input.required<Item[]>();
+  trackById = (_: number, i: Item) => i.id;
+}
+```
+
+```typescript
+// Computed signal instead of template method call
+@Component({
+  template: `<p>Total: {{ formattedTotal() }}</p>`,
+})
+export class CartComponent {
+  items = signal<CartItem[]>([]);
+
+  // Memoized — only recomputes when items() changes
+  total = computed(() => this.items().reduce((s, i) => s + i.price * i.qty, 0));
+  formattedTotal = computed(() =>
+    new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(this.total())
+  );
+}
+```
+
+```typescript
+// Running non-UI work outside Angular zone
+@Injectable({ providedIn: 'root' })
+export class PollingService {
+  private ngZone = inject(NgZone);
+
+  startPolling(callback: () => void, intervalMs: number): () => void {
+    let id: ReturnType<typeof setInterval>;
+    this.ngZone.runOutsideAngular(() => {
+      id = setInterval(() => {
+        // Run callback back inside zone to trigger CD if needed
+        this.ngZone.run(callback);
+      }, intervalMs);
+    });
+    return () => clearInterval(id);
+  }
+}
+```
+
+## Details
+
+**Change detection cost model:** In the default strategy, Angular traverses the entire component tree on every browser event (click, input, scroll, setTimeout, XHR). With `OnPush`, Angular marks a component as "dirty" only when:
+
+- An `@Input()` reference changes (new object/array reference)
+- A signal read inside the component template emits
+- An observable bound with `async` pipe emits
+- `ChangeDetectorRef.markForCheck()` is called explicitly
+
+**`trackBy` mechanics:** Without `trackBy`, Angular compares list items by identity. When the array reference changes (even with the same data), Angular destroys and recreates all DOM nodes — re-triggering child lifecycle hooks. `trackBy` returns a key; if the key matches an existing node, Angular reuses the DOM element and only updates the changed properties.
+
+**Virtual scrolling sizing:** `CdkVirtualScrollViewport` requires `itemSize` (in pixels) for fixed-height items. For variable-height items, use `AutoSizeVirtualScrollStrategy` from CDK (experimental). The viewport must have an explicit height for scrolling to work.
+
+**`NgZone.runOutsideAngular` use cases:**
+
+- WebSocket message handlers that update a signal
+- `requestAnimationFrame` loops for canvas rendering
+- `setInterval` for polling when only some callbacks need UI updates
+
+**Bundle performance:** `@defer` creates a separate chunk for the deferred component. Use `ng build --stats-json && npx webpack-bundle-analyzer dist/stats.json` to verify chunk sizes. Set `bundleBudgets` in `angular.json` to fail the build if chunks exceed defined thresholds.
+
+**Profiling with Angular DevTools:** Install the Angular DevTools Chrome extension. In the "Profiler" tab, record a change detection cycle and inspect which components checked and how long each took. Components with unnecessary check counts are candidates for `OnPush` or signal migration.
+
+**Memoization with pure pipes:** A `pure: true` pipe (default) is essentially a memoized function — Angular caches the result for the same input references. For expensive formatting applied in a large `*ngFor`, a pure pipe avoids recomputing the format on every CD cycle.
+
+## Source
+
+https://angular.dev/guide/best-practices/runtime-performance
+
+## 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/angular-performance-patterns/skill.yaml

@@ -0,0 +1,45 @@
+name: angular-performance-patterns
+version: '1.0.0'
+description: Optimize Angular app performance with OnPush, trackBy, virtual scrolling, and deferrable views
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - angular.json
+  - '**/*.component.ts'
+  - '**/*.component.html'
+  - '**/*.service.ts'
+  - '**/*.module.ts'
+related_skills:
+  - angular-component-pattern
+  - angular-signals-pattern
+  - angular-lazy-loading
+  - angular-pipe-pattern
+stack_signals:
+  - angular
+  - typescript
+  - rxjs
+keywords:
+  - OnPush
+  - trackBy
+  - virtual-scrolling
+  - deferrable-views
+  - performance
+  - memoization
+  - zoneless
+  - CdkVirtualScrollViewport
+metadata:
+  author: angular.dev
+  upstream: 'angular.dev/guide/best-practices/runtime-performance'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/angular-pipe-pattern/SKILL.md

@@ -0,0 +1,126 @@
+# Angular Pipe Pattern
+
+> Create custom Angular pipes for pure data transformation and use built-in pipes correctly to keep templates declarative and performant
+
+## When to Use
+
+- Formatting data in templates (currency, date, truncation, pluralization) without component logic
+- Reusing a display transformation across multiple templates
+- Replacing complex template expressions (`{{ item.name.length > 20 ? item.name.slice(0, 20) + '...' : item.name }}`) with a readable pipe
+- Using `AsyncPipe` to handle observable/promise subscriptions and change detection automatically
+- Building pipes that inject services for locale-aware or permission-aware formatting
+
+## Instructions
+
+1. Implement the `PipeTransform` interface and decorate with `@Pipe({ name: 'myPipe', standalone: true })`.
+2. Keep pipes pure by default (`pure: true` is the default). Pure pipes only re-run when the input reference changes — this is a significant performance optimization.
+3. Mark a pipe `pure: false` (impure) only when the output depends on something other than the input arguments (e.g., reading from a changing service or the current time). Impure pipes run on every change detection cycle.
+4. Inject services into pipes via `inject()` for locale-aware formatting, permission checks, or translation.
+5. Use `| async` in templates instead of manual subscriptions — it subscribes, unsubscribes on destroy, and triggers change detection when values emit.
+6. Prefer `| date:'shortDate'`, `| currency:'USD'`, `| number:'1.2-2'`, `| titlecase`, `| keyvalue` built-ins before writing custom pipes.
+7. Name pipes with a consistent convention: `camelCase` in the class, matching `camelCase` in the `name` field. Use verb-noun for transformation pipes (`truncate`, `highlight`, `formatBytes`).
+8. Add the standalone pipe to the `imports` array of components that use it.
+
+```typescript
+// truncate.pipe.ts — pure transformation
+import { Pipe, PipeTransform } from '@angular/core';
+
+@Pipe({ name: 'truncate', standalone: true })
+export class TruncatePipe implements PipeTransform {
+  transform(value: string, limit = 100, suffix = '...'): string {
+    if (!value) return '';
+    return value.length > limit ? `${value.slice(0, limit)}${suffix}` : value;
+  }
+}
+```
+
+```typescript
+// format-bytes.pipe.ts — custom formatting with multiple args
+@Pipe({ name: 'formatBytes', standalone: true })
+export class FormatBytesPipe implements PipeTransform {
+  transform(bytes: number, decimals = 2): string {
+    if (bytes === 0) return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${sizes[i]}`;
+  }
+}
+```
+
+```typescript
+// highlight.pipe.ts — service-injected pipe
+import { Pipe, PipeTransform, inject } from '@angular/core';
+import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
+
+@Pipe({ name: 'highlight', standalone: true })
+export class HighlightPipe implements PipeTransform {
+  private sanitizer = inject(DomSanitizer);
+
+  transform(text: string, search: string): SafeHtml {
+    if (!search) return text;
+    const regex = new RegExp(`(${search})`, 'gi');
+    const highlighted = text.replace(regex, '<mark>$1</mark>');
+    return this.sanitizer.bypassSecurityTrustHtml(highlighted);
+  }
+}
+```
+
+```html
+<!-- Template usage -->
+<p>{{ product.description | truncate:150 }}</p>
+<p>{{ fileSize | formatBytes }}</p>
+<p [innerHTML]="product.name | highlight:searchTerm"></p>
+<li *ngFor="let user of users$ | async">{{ user.name }}</li>
+<p>{{ price | currency:'EUR':'symbol':'1.2-2' | uppercase }}</p>
+```
+
+## Details
+
+**Pure vs impure pipes:** Pure pipes cache their result for a given set of input references. If the input is the same object reference, Angular returns the cached result without calling `transform()` again. This makes pipes very efficient with `OnPush` components. Impure pipes (`pure: false`) run on every change detection cycle — use sparingly and only when necessary (e.g., a pipe filtering a mutable array).
+
+**`AsyncPipe` advantages over manual subscriptions:**
+
+- Automatically calls `subscribe()` and `unsubscribe()` on the observable lifecycle tied to the component
+- Calls `markForCheck()` on `OnPush` components when new values arrive — without this, `OnPush` components won't update
+- Handles both `Observable` and `Promise` transparently
+
+**Pipe chaining:** Pipes compose left to right: `{{ value | pipe1 | pipe2:arg }}`. Each pipe's output is the next pipe's input.
+
+**Avoiding impure pipes for filtering/sorting:** A common mistake is creating an impure pipe that filters or sorts an array. Because the array reference doesn't change when items are pushed, a pure pipe won't re-run. Better solutions: filter in the component with `computed()` or a getter, or create a new array reference when the data changes.
+
+**Locale-aware built-in pipes:** `DatePipe`, `CurrencyPipe`, `DecimalPipe`, and `PercentPipe` all use Angular's locale system. Provide a locale with `{ provide: LOCALE_ID, useValue: 'de-DE' }` to format numbers and dates for the user's locale automatically.
+
+**Testing pipes:**
+
+```typescript
+describe('TruncatePipe', () => {
+  const pipe = new TruncatePipe();
+  it('truncates long strings', () => {
+    expect(pipe.transform('a'.repeat(200), 50)).toBe('a'.repeat(50) + '...');
+  });
+  it('returns short strings unchanged', () => {
+    expect(pipe.transform('short', 50)).toBe('short');
+  });
+});
+```
+
+## Source
+
+https://angular.dev/guide/pipes
+
+## 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/angular-pipe-pattern/skill.yaml

@@ -0,0 +1,44 @@
+name: angular-pipe-pattern
+version: '1.0.0'
+description: Create custom Angular pipes for pure data transformation and leverage built-in pipes correctly
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - angular.json
+  - '**/*.component.ts'
+  - '**/*.component.html'
+  - '**/*.service.ts'
+  - '**/*.module.ts'
+related_skills:
+  - angular-component-pattern
+  - angular-performance-patterns
+  - angular-rxjs-patterns
+  - angular-standalone-components
+stack_signals:
+  - angular
+  - typescript
+  - rxjs
+keywords:
+  - pipe
+  - PipeTransform
+  - pure-pipe
+  - impure-pipe
+  - async-pipe
+  - custom-pipe
+  - transform
+metadata:
+  author: angular.dev
+  upstream: 'angular.dev/guide/pipes'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/angular-reactive-forms/SKILL.md

@@ -0,0 +1,136 @@
+# Angular Reactive Forms
+
+> Build type-safe reactive forms with FormGroup, FormControl, Validators, and dynamic FormArrays
+
+## When to Use
+
+- Building forms with non-trivial validation logic or cross-field validators
+- Creating dynamic forms where controls are added/removed at runtime
+- Needing to programmatically reset, patch, or observe form value changes via observables
+- Replacing template-driven forms to gain full TypeScript type safety (Angular 14+ typed forms)
+- Building wizard-style multi-step forms backed by a single FormGroup
+
+## Instructions
+
+1. Use `FormBuilder` (inject via `inject(FormBuilder)`) to construct `FormGroup` and `FormControl` — it reduces boilerplate significantly.
+2. Type your forms explicitly: `FormGroup<{ email: FormControl<string>; password: FormControl<string> }>`. Angular 14+ infers types from the `FormBuilder.nonNullable` builder.
+3. Use `FormBuilder.nonNullable` when controls should never be null — it eliminates null narrowing on `.value` reads.
+4. Attach built-in validators via `Validators.required`, `Validators.email`, `Validators.minLength(n)`. Compose them as an array.
+5. Write custom validators as plain functions: `(control: AbstractControl): ValidationErrors | null => ...`. Prefer synchronous validators; use async validators only for server-side checks (e.g., username availability).
+6. Use `FormArray` for variable-length lists (e.g., multiple phone numbers, line items). Access controls via `.controls` and mutate via `.push()`, `.removeAt()`.
+7. Subscribe to `form.statusChanges` and `form.valueChanges` sparingly — prefer template binding to `form.valid` and `form.value` in the submit handler.
+8. Call `form.markAllAsTouched()` before showing validation errors on submit to trigger error display for untouched fields.
+
+```typescript
+import { Component, inject } from '@angular/core';
+import {
+  FormBuilder,
+  FormGroup,
+  FormControl,
+  FormArray,
+  Validators,
+  AbstractControl,
+  ValidationErrors,
+} from '@angular/forms';
+
+function noWhitespace(control: AbstractControl): ValidationErrors | null {
+  const trimmed = (control.value ?? '').trim();
+  return trimmed.length === 0 && control.value?.length > 0 ? { whitespace: true } : null;
+}
+
+@Component({
+  selector: 'app-signup',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="onSubmit()">
+      <input formControlName="email" type="email" />
+      <span *ngIf="form.controls.email.errors?.['email']">Invalid email</span>
+
+      <div formArrayName="phones">
+        <div *ngFor="let phone of phones.controls; let i = index">
+          <input [formControlName]="i" type="tel" />
+          <button type="button" (click)="removePhone(i)">Remove</button>
+        </div>
+        <button type="button" (click)="addPhone()">Add phone</button>
+      </div>
+
+      <button type="submit" [disabled]="form.invalid">Submit</button>
+    </form>
+  `,
+})
+export class SignupComponent {
+  private fb = inject(FormBuilder).nonNullable;
+
+  form = this.fb.group({
+    email: ['', [Validators.required, Validators.email]],
+    password: ['', [Validators.required, Validators.minLength(8), noWhitespace]],
+    phones: this.fb.array([this.fb.control('')]),
+  });
+
+  get phones(): FormArray<FormControl<string>> {
+    return this.form.controls.phones;
+  }
+
+  addPhone(): void {
+    this.phones.push(this.fb.control(''));
+  }
+
+  removePhone(index: number): void {
+    this.phones.removeAt(index);
+  }
+
+  onSubmit(): void {
+    if (this.form.invalid) {
+      this.form.markAllAsTouched();
+      return;
+    }
+    console.log(this.form.getRawValue());
+  }
+}
+```
+
+## Details
+
+**Typed forms (Angular 14+):** Before Angular 14, `.value` returned `any`. Typed forms make the value inferred from the control definition. Use `FormBuilder.nonNullable` (or `new FormControl<string>('')`) to avoid `string | null` everywhere. The `getRawValue()` method returns values including disabled controls; `.value` skips them.
+
+**Cross-field validators:** Attach at the `FormGroup` level, not the control level. The validator receives the entire group and can compare controls:
+
+```typescript
+function passwordsMatch(group: AbstractControl): ValidationErrors | null {
+  const pw = group.get('password')?.value;
+  const confirm = group.get('confirm')?.value;
+  return pw === confirm ? null : { mismatch: true };
+}
+this.fb.nonNullable.group({ password: '', confirm: '' }, { validators: passwordsMatch });
+```
+
+**Async validators:** Return `Observable<ValidationErrors | null>` or `Promise<ValidationErrors | null>`. Angular sets `status` to `'PENDING'` while the validator runs. Debounce with `switchMap` to avoid hammering the server on every keystroke.
+
+**`updateOn` strategy:** By default, validation runs on every value change. Use `updateOn: 'blur'` or `updateOn: 'submit'` on a control or group to reduce validation frequency:
+
+```typescript
+this.fb.nonNullable.control('', { validators: Validators.required, updateOn: 'blur' });
+```
+
+**Resetting vs patching:** `form.reset()` clears all controls and resets touched/dirty flags. `form.patchValue({ email: 'x' })` updates only the supplied keys. `form.setValue({...})` requires every key to be provided or throws. Prefer `patchValue` when loading partial data.
+
+**Performance:** Avoid creating reactive form controls inside `*ngFor` loops without caching — Angular recreates them on every change detection cycle. Use `FormArray` and index-based `formControlName` instead.
+
+## Source
+
+https://angular.dev/guide/forms/reactive-forms
+
+## 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/angular-reactive-forms/skill.yaml

@@ -0,0 +1,44 @@
+name: angular-reactive-forms
+version: '1.0.0'
+description: Build type-safe reactive forms with FormGroup, FormControl, Validators, and dynamic form arrays
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - angular.json
+  - '**/*.component.ts'
+  - '**/*.component.html'
+  - '**/*.service.ts'
+  - '**/*.module.ts'
+related_skills:
+  - angular-component-pattern
+  - angular-signals-pattern
+  - angular-service-di
+  - ts-utility-types
+stack_signals:
+  - angular
+  - typescript
+  - rxjs
+keywords:
+  - reactive-forms
+  - FormGroup
+  - FormControl
+  - FormArray
+  - Validators
+  - form-builder
+  - typed-forms
+metadata:
+  author: angular.dev
+  upstream: 'angular.dev/guide/forms/reactive-forms'
+state:
+  persistent: false
+  files: []
+depends_on: []