skill: angular

should_trigger:
  - prompt: "Migrate this Angular app from NgModules to standalone components."
    why: "Standalone migration is central modern Angular work."
  - prompt: "Why is my Angular view not updating in zoneless mode?"
    why: "Zoneless change detection and signals are Angular-specific."
  - prompt: "Replace *ngFor with @for and track expressions."
    why: "Built-in control flow migration belongs to Angular."
  - prompt: "Use input() signals instead of decorator @Input in this component."
    why: "Signal inputs are Angular-specific."
  - prompt: "Monta una app Angular con componente standalone y signals."
    why: "Spanish Angular standalone/signals request triggers this skill."

should_not_trigger:
  - prompt: "Fix a React hook state bug."
    route_to: "react"
    why: "React hooks are not Angular."
  - prompt: "Implement a Next.js server component."
    route_to: "nextjs"
    why: "Next.js App Router/RSC is a separate stack."
  - prompt: "Explain TypeScript conditional types."
    route_to: "typescript"
    why: "Pure TypeScript without Angular belongs to TypeScript."
  - prompt: "Build a NestJS backend module."
    route_to: "nestjs"
    why: "NestJS is backend DI; Angular is frontend framework."

capability:
  - scenario: "A brownfield Angular app uses NgModules, decorator inputs and Zone.js; the user wants a safe modern migration."
    must_include:
      - "Detects Angular version and brownfield vs greenfield before changing architecture."
      - "Migrates incrementally to standalone components rather than rewriting everything."
      - "Uses signals/input() and built-in @if/@for/@defer control flow where appropriate."
      - "Explains zoneless change detection and avoids detectChanges() as a default patch."
      - "Keeps providers in app.config.ts/provide* APIs for modern bootstrap."
      - "Uses RxJS interop deliberately with toSignal/toObservable when needed."
      - "Routes pure TypeScript or backend NestJS questions to those skills."

# angular evals

Trigger and capability checks for modern Angular work.

# Incremental migration — legacy Angular → standalone, signals, zoneless

Migrate a working app in small reversible steps. Each step has an official schematic; run them
one at a time, commit, and verify the app still builds and tests pass before the next.

## Order of operations

1. Update Angular first, then migrate. `ng update @angular/core @angular/cli` runs the
   bundled migrations for the version you land on. Do not migrate APIs on an old major.
2. Standalone components/directives/pipes.
3. Built-in control flow (`*ngIf`/`*ngFor` → `@if`/`@for`).
4. Signal inputs/outputs.
5. Zoneless (last — it has the widest blast radius).
6. Test runner (Karma/Jasmine → Vitest), independently of the above.

## 1. NgModule → standalone

```bash
ng generate @angular/core:standalone
```

Run it three times, choosing each mode in turn:
- *Convert all components, directives and pipes to standalone*
- *Remove unnecessary NgModule classes*
- *Bootstrap the application using standalone APIs* (rewrites `main.ts` to `bootstrapApplication`)

After the last pass you should have an `app.config.ts` with `provideRouter`,
`provideHttpClient`, etc. Delete the now-empty `AppModule`.

## 2. Control flow: *ngIf / *ngFor → @if / @for

```bash
ng generate @angular/core:control-flow
```

This rewrites templates automatically. Review every converted `@for`: the schematic inserts a
`track` expression (often `track $index` as a safe default). Replace `$index` with a stable key
(`track item.id`) wherever items have identity, so the DOM reuses nodes on reorder. Once
converted you can drop `CommonModule` imports that only existed for the directives.

## 3. Decorator inputs/outputs → signals

```bash
ng generate @angular/core:signal-input-migration
ng generate @angular/core:output-migration
ng generate @angular/core:signal-queries-migration   # @ViewChild/@ContentChild -> viewChild()/contentChild()
```

What changes for callers inside the class:
- `this.userId` (a value) becomes `this.userId()` (a signal read). The migration updates
  template and class reads, but check any code that assigned to the field — signal inputs are
  read-only; lift writable state into a separate `signal()` or use `model()` for two-way.
- `@Output() saved = new EventEmitter()` → `saved = output()`, emit with `saved.emit(x)`.

## 4. Zone.js → zoneless go-live checklist

Flip this last, after signals and control flow are in place.

- [ ] Add `provideZonelessChangeDetection()` to the app providers (and to test providers).
- [ ] Remove `provideZoneChangeDetection()` if present.
- [ ] Delete the `zone.js` import from `polyfills`/`main.ts`; remove `zone.js` from
      `package.json` and the `polyfills` entry in `angular.json`.
- [ ] Audit every component for state read in the template that is **not** a signal — under
      zoneless, a plain field mutated outside an event handler will not repaint. Convert it to a
      `signal()`, or ensure the change originates from a tracked source (signal, async pipe,
      template event, router).
- [ ] Replace any `setTimeout`/`Promise`/3rd-party-callback that mutates view state with a
      signal write, or call `ChangeDetectorRef.markForCheck()` from inside it.
- [ ] Search for `ChangeDetectorRef.detectChanges()` "fix-it" calls and the `NgZone.run()`
      escape hatch — both are smells that some state isn't a signal yet.
- [ ] Run the app and click through; watch for views that update only on the *next* unrelated
      interaction (the classic zoneless-miss symptom).

## 5. Karma/Jasmine → Vitest

New Angular 21 projects use Vitest by default. For an existing project, switch the test builder
to the Vitest-based runner in `angular.json` and migrate specs: Jasmine's `spyOn`/`jasmine.
createSpy` map to Vitest's `vi.fn`/`vi.spyOn`, and `expect().toHaveBeenCalled()` etc. are
compatible. Keep `TestBed`; only the runner and the mocking API change. Add
`provideZonelessChangeDetection()` to test module providers and prefer `await
fixture.whenStable()` over manual `detectChanges()` loops.

# Signals vs RxJS — when to use which, and how to bridge

Signals and RxJS coexist in modern Angular. Signals are the default for UI state and
synchronous derivation; RxJS still owns asynchronous *streams* of events over time.

## Decision matrix

| You have… | Use | Why |
|-----------|-----|-----|
| A piece of UI state read in a template | `signal()` | Pull-based, glitch-free, drives zoneless CD directly |
| A value derived from other state | `computed()` | Memoized, lazy, no manual subscription |
| One async fetch tied to inputs | `httpResource()` / `resource()` | Gives `value/isLoading/error/reload`, auto-refetch, no leak |
| A stream over time (websocket, key events, intervals) | RxJS `Observable` | Signals are values-now, not events-over-time |
| Debounce / throttle / retry / cancel-in-flight | RxJS (`debounceTime`, `switchMap`, `retry`) | These are stream operators; signals have no time dimension |
| A writable copy that resets when a source changes | `linkedSignal()` | Purpose-built; avoids an effect-to-sync anti-pattern |

Rule of thumb: **state → signals, events → observables.** When in doubt, start with a signal;
escalate to RxJS only when you need an operator that models time.

## Interop

`toSignal()` and `toObservable()` are the two bridges (`@angular/core/rxjs-interop`).

```typescript
import { toSignal, toObservable, takeUntilDestroyed } from '@angular/core/rxjs-interop';

// Observable -> Signal: subscribe is managed for you; unsubscribes on destroy.
private search = signal('');
results = toSignal(
  toObservable(this.search).pipe(
    debounceTime(300),
    switchMap(q => this.api.search(q)),  // switchMap cancels the prior request
  ),
  { initialValue: [] as Result[] },
);
```

- `toSignal(obs$, { initialValue })` — read `results()` in the template; the subscription is
  cleaned up automatically when the injection context is destroyed.
- `toObservable(sig)` — turn a signal into a stream so you can apply operators. It emits on the
  microtask queue, not synchronously.
- `takeUntilDestroyed()` — for the rare hand-rolled subscription, this completes it when the
  component/service is destroyed. Use it instead of a manual `Subscription` + `ngOnDestroy`.

## effect() pitfalls

`effect()` is for side effects, not derivation. Common ways it goes wrong:

```typescript
// Pitfall 1 — infinite loop: an effect that writes a signal it also reads.
effect(() => this.count.set(this.count() + 1)); // re-runs forever

// Pitfall 2 — using an effect to derive state. Use computed() instead.
effect(() => this.total.set(this.qty() * this.price())); // double-fires, hidden graph
// Fix:
total = computed(() => this.qty() * this.price());

// Pitfall 3 — wanting to write without creating a dependency: wrap in untracked().
effect(() => {
  const id = this.userId();           // tracked dependency
  untracked(() => this.log.push(id)); // read/write here is NOT a dependency
});
```

- An effect runs once on creation and again whenever any signal it *reads* changes.
- Reading a signal inside `untracked(() => …)` does not register it as a dependency.
- If you find yourself calling `.set()` from inside an effect to feed the template, you almost
  certainly want `computed()` or `linkedSignal()`.

## resource() / httpResource() patterns

```typescript
// Dependent fetch: the resource re-runs when team() changes.
team = signal('eng');
users = httpResource<User[]>(() => `/api/users?team=${this.team()}`);

// Mutate then refresh:
async addUser(u: User) {
  await firstValueFrom(this.http.post('/api/users', u));
  this.users.reload();
}

// Loading / error in the template:
// @if (users.isLoading()) { <app-spinner/> }
// @else if (users.error()) { <p>Failed</p> }
// @else { @for (u of users.value(); track u.id) { … } }
```

- A `resource()` cancels the previous load when its `params` change (it passes an `AbortSignal`
  to the loader) — use it for `fetch` cancellation without writing RxJS.
- `httpResource()` is GET-oriented and reactive. For POST/PUT/DELETE keep `HttpClient` and call
  `reload()` after the mutation.

#!/usr/bin/env bash
#
# verify.sh — Angular modern-baseline copy-banlist (heuristic lint, NOT a compiler).
#
# USAGE
#   bash scripts/verify.sh [PATH ...]
#   Run from your Angular project root. With no args it scans ./src (falling back
#   to the current dir). Pass explicit paths to scope it to just-edited files:
#     bash scripts/verify.sh src/app/users
#
# WHAT IT DOES
#   Greps Angular .ts/.html sources for legacy patterns this skill bans, so the
#   agent can self-correct toward standalone + signals + built-in control flow:
#     - @NgModule in new code
#     - legacy structural directives  *ngIf / *ngFor / *ngSwitch
#     - decorator I/O  @Input() / @Output()
#     - @for blocks missing a `track` expression
#     - constructor-based DI (constructor(private x: X)) where inject() is the rule
#   Each hit prints file:line. It is a best-effort heuristic, not a parser, so it
#   may have false positives/negatives — treat it as a hint.
#
# GUARANTEES
#   - Read-only: never writes, fixes, installs, or hits the network.
#   - Exits 0 on an empty/clean target (no sources, or no hits) — no false failure.
#   - Exits 1 only when at least one banned pattern is found, so it can gate a loop.
#   - Portable to stock macOS bash 3.2 (no mapfile, no associative arrays).

set -u

if [ -t 1 ] && command -v tput >/dev/null 2>&1; then
  RED="$(tput setaf 1)"; GREEN="$(tput setaf 2)"; YELLOW="$(tput setaf 3)"; RESET="$(tput sgr0)"
else
  RED=""; GREEN=""; YELLOW=""; RESET=""
fi

hits=0
ok() { printf '%s\n' "${GREEN}ok${RESET}  $1"; }

# --- resolve scan roots -----------------------------------------------------
roots=""
if [ "$#" -gt 0 ]; then
  roots="$*"
elif [ -d ./src ]; then
  roots="./src"
else
  roots="."
fi

# Collect candidate Angular source files (.ts/.html), skipping vendor/build dirs
# and *.spec.ts / *.d.ts. Newline-delimited list; empty if nothing matches.
files="$(
  find $roots \
    \( -name node_modules -o -name dist -o -name .angular -o -name .git -o -name coverage \) -prune -o \
    -type f \( -name '*.ts' -o -name '*.html' \) \
    ! -name '*.spec.ts' ! -name '*.d.ts' -print 2>/dev/null
)"

if [ -z "$files" ]; then
  printf '%s\n' "${YELLOW}skip${RESET} no Angular .ts/.html sources under: $roots"
  exit 0
fi

# Grep a pattern across all files, reporting each match as "file:line: text".
# $1 = ERE pattern, $2 = human label. Counts hits into the global $hits.
scan() {
  pattern="$1"; label="$2"
  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
    [ -n "$f" ] || continue
    grep -nE "$pattern" "$f" 2>/dev/null | sed "s|^|$f:|"
  done)"
  if [ -n "$out" ]; then
    printf '%s\n' "$out" | while IFS= read -r m; do
      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} $label  $m"
    done
    n="$(printf '%s\n' "$out" | grep -c . )"
    hits=$((hits + n))
  else
    ok "no $label"
  fi
}

# @for openers that do NOT contain `track` on the same line — track is required.
scan_for_track() {
  out="$(printf '%s\n' "$files" | while IFS= read -r f; do
    [ -n "$f" ] || continue
    grep -nE '@for[[:space:]]*\(' "$f" 2>/dev/null | grep -v 'track' | sed "s|^|$f:|"
  done)"
  if [ -n "$out" ]; then
    printf '%s\n' "$out" | while IFS= read -r m; do
      [ -n "$m" ] && printf '%s\n' "${RED}HIT${RESET} @for without track (track is required)  $m"
    done
    n="$(printf '%s\n' "$out" | grep -c . )"
    hits=$((hits + n))
  else
    ok "no @for without track"
  fi
}

printf '=== Angular banlist (%s files under %s) ===\n' "$(printf '%s\n' "$files" | grep -c .)" "$roots"

# 1. NgModule in new code.
scan '@NgModule' '@NgModule (use standalone components)'

# 2. Legacy structural directives.
scan '\*ng(If|For|Switch)\b' 'legacy *ngIf/*ngFor/*ngSwitch (use @if/@for/@switch)'

# 3. Decorator I/O.
scan '@(Input|Output)\(' '@Input()/@Output() decorator (use input()/output())'

# 4. @for blocks missing the required `track` expression.
scan_for_track

# 5. Constructor-based DI.
scan 'constructor[[:space:]]*\([^)]*(private|public|protected|readonly)[[:space:]]+[A-Za-z_]+[[:space:]]*:' 'constructor DI (use inject())'

printf '\n'
if [ "$hits" -gt 0 ]; then
  printf '%sFAIL%s %d banned-pattern hit(s) — migrate toward standalone + signals.\n' "$RED" "$RESET" "$hits"
  exit 1
fi
printf '%sPASS%s clean — no banned legacy Angular patterns found.\n' "$GREEN" "$RESET"
exit 0