agent-directives 0.3.0 → 0.4.0

package/rules/angular/patterns.md

@@ -0,0 +1,287 @@
+---
+name: angular-patterns
+description: Concrete Angular application patterns — smart/dumb component split, service-layer ownership, routing/guards/resolvers, HTTP interceptors, and reactive state with signals or RxJS.
+version: 1.0.0
+required: false
+category: angular
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+source_urls:
+  - https://angular.dev/guide/components
+  - https://angular.dev/guide/routing
+  - https://angular.dev/guide/http
+  - https://angular.dev/guide/di
+  - https://angular.dev/guide/signals
+applies_to:
+  - src/app/**/*.component.ts
+  - src/app/**/*.component.html
+  - src/app/**/*.service.ts
+  - src/app/**/*.store.ts
+  - src/app/**/*.routes.ts
+  - src/app/**/*.guard.ts
+  - src/app/**/*.resolver.ts
+  - src/app/**/*.interceptor.ts
+---
+
+# Angular Patterns Rules
+
+**Load when:** Building or reviewing Angular feature code that crosses components and services — data flow, routing, HTTP, forms, or state.
+
+## Version Awareness
+
+Functional guards/resolvers/interceptors, `inject()`, signal inputs, `resource()`, `linkedSignal`, and `withComponentInputBinding()` are version-gated. Match the project's Angular version before introducing a pattern, and keep an existing file consistent with the style already in it.
+
+## Sources
+
+- Angular Components Guide — https://angular.dev/guide/components
+- Angular Routing Guide — https://angular.dev/guide/routing
+- Angular HTTP Guide — https://angular.dev/guide/http
+- Angular Dependency Injection Guide — https://angular.dev/guide/di
+- Angular Signals Guide — https://angular.dev/guide/signals
+
+## Rules
+
+### Smart / dumb component split
+
+Smart (container) components own data fetching and state. Dumb (presentational) components receive inputs and emit outputs only — no service injection, no router access.
+
+```typescript
+// Smart — owns data
+@Component({
+  selector: 'app-user-page',
+  standalone: true,
+  imports: [UserCardComponent],
+  template: `
+    @if (userResource.isLoading()) { <app-spinner /> }
+    @else if (userResource.error()) { <app-error /> }
+    @else { <app-user-card [user]="userResource.value()!" (select)="onSelect($event)" /> }
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserPageComponent {
+  private userService = inject(UserService);
+  userId = input.required<string>();
+
+  userResource = resource({
+    request: () => ({ id: this.userId() }),
+    loader: ({ request }) => firstValueFrom(this.userService.getUser(request.id)),
+  });
+
+  onSelect(id: string) { /* navigate or update state */ }
+}
+```
+
+```typescript
+// Dumb — pure presentation, no inject(), no router
+@Component({
+  selector: 'app-user-card',
+  standalone: true,
+  template: `<button (click)="select.emit(user().id)">{{ user().name }}</button>`,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserCardComponent {
+  user = input.required<User>();
+  select = output<string>();
+}
+```
+
+### Service layer
+
+Services own all data access and business logic. Components delegate — no `HttpClient` in components, no `fetch()` in components.
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class UserService {
+  private http = inject(HttpClient);
+
+  getUsers(): Observable<User[]> {
+    return this.http.get<User[]>('/api/users');
+  }
+
+  getUser(id: string): Observable<User> {
+    return this.http.get<User>(`/api/users/${id}`);
+  }
+}
+```
+
+- One service per cohesive domain concept. Do not bury unrelated APIs in a god service.
+- Scope a service to a component/route subtree (component `providers: [...]`) only when its lifecycle must follow that subtree. Otherwise prefer `providedIn: 'root'`.
+
+### Reactive state
+
+```typescript
+// Local state
+count = signal(0);
+doubled = computed(() => this.count() * 2);
+selectedItem = linkedSignal(() => this.items()[0]);
+
+// Bridge an Observable into a signal
+users = toSignal(this.userService.getUsers(), { initialValue: [] });
+```
+
+- Derived values live in `computed` / `linkedSignal` — never in a separate writable signal updated by `effect`.
+- Use `takeUntilDestroyed(this.destroyRef)` for manual subscriptions:
+
+```typescript
+export class UserComponent {
+  private destroyRef = inject(DestroyRef);
+  private userService = inject(UserService);
+
+  ngOnInit() {
+    this.userService.updates$
+      .pipe(takeUntilDestroyed(this.destroyRef))
+      .subscribe(update => this.handleUpdate(update));
+  }
+}
+```
+
+### Routing
+
+```typescript
+// app.routes.ts (or feature.routes.ts)
+export const routes: Routes = [
+  { path: '', component: HomeComponent },
+  {
+    path: 'admin',
+    canMatch: [authGuard],                              // canMatch prevents the chunk from loading at all
+    loadChildren: () => import('./admin/admin.routes').then(m => m.ADMIN_ROUTES),
+  },
+  {
+    path: 'users/:id',
+    resolve: { user: userResolver },
+    loadComponent: () => import('./users/user-detail.component').then(m => m.UserDetailComponent),
+  },
+];
+```
+
+- Use `canMatch` (not `canActivate`) for sensitive routes — the route module never loads for unauthorized users, so the code isn't shipped to them.
+- Lazy-load every feature with `loadChildren` (or `loadComponent` for a single route).
+- Pre-fetch with `resolve` when the destination cannot meaningfully render without the data.
+- Enable component input binding once at app level (`withComponentInputBinding()`), then bind route params via `input()`:
+
+```typescript
+export class UserDetailComponent {
+  id = input.required<string>();  // route param :id binds automatically
+}
+```
+
+### Functional guards and resolvers
+
+```typescript
+export const authGuard: CanActivateFn = () => {
+  const auth = inject(AuthService);
+  return auth.isAuthenticated()
+    ? true
+    : inject(Router).createUrlTree(['/login']);
+};
+
+export const userResolver: ResolveFn<User> = (route) =>
+  inject(UserService).getUser(route.paramMap.get('id')!);
+```
+
+- Prefer functional `CanActivateFn` / `CanMatchFn` / `ResolveFn` / `HttpInterceptorFn` over class-based equivalents on standalone-first projects.
+
+### HTTP interceptors
+
+```typescript
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).token();
+  if (!token) return next(req);
+  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }));
+};
+
+// app.config.ts
+provideHttpClient(withInterceptors([authInterceptor, errorInterceptor, retryInterceptor]))
+```
+
+- Register cross-cutting concerns (auth, error mapping, retries, logging) as interceptors. Do not duplicate header logic across services.
+- Keep interceptors small and composable; one concern per interceptor.
+
+### Forms
+
+Match the project's existing form strategy. For complex validation, prefer Reactive Forms. For v21+ projects starting fresh, Signal Forms are appropriate.
+
+```typescript
+// Reactive Forms — standard approach for most apps
+export class LoginComponent {
+  private fb = inject(FormBuilder);
+
+  form = this.fb.nonNullable.group({
+    email: ['', [Validators.required, Validators.email]],
+    password: ['', [Validators.required, Validators.minLength(8)]],
+  });
+
+  submit() {
+    if (this.form.invalid) return;
+    const { email, password } = this.form.getRawValue();
+    // ...
+  }
+}
+```
+
+- Use `fb.nonNullable` / `NonNullableFormBuilder` so controls are typed as `T` rather than `T | null`.
+- Avoid mixing reactive and template-driven forms in the same form.
+
+### Async data with `resource()`
+
+Use `resource()` for reactive async fetching that depends on signals — it manages loading/error/value automatically and reloads when the request signal changes.
+
+```typescript
+export class UserDetailComponent {
+  userId = input.required<string>();
+
+  userResource = resource({
+    request: () => ({ id: this.userId() }),
+    loader: ({ request }) =>
+      firstValueFrom(inject(UserService).getUser(request.id)),
+  });
+}
+```
+
+State: `userResource.value()`, `userResource.isLoading()`, `userResource.error()`, `userResource.reload()`.
+
+### RxJS operator choice
+
+| Operator | Use for |
+| --- | --- |
+| `switchMap` | Search, navigation, latest-wins |
+| `mergeMap` | Independent parallel requests |
+| `exhaustMap` | Form submits — ignore re-clicks until current completes |
+| `concatMap` | Ordered queueing |
+
+Always end an HTTP-backed inner stream with `catchError` so the outer stream survives failures.
+
+### Rendering strategies
+
+- **CSR** (default) — standard SPA.
+- **SSR + Hydration** — `ng add @angular/ssr`. Improves first paint and SEO.
+- **SSG / Prerender** — for content-heavy public routes.
+
+Under SSR, never touch `window`, `document`, `localStorage`, or `navigator` directly — gate with `isPlatformBrowser(this.platformId)` or inject via the `DOCUMENT` token.
+
+### Accessibility
+
+- Reuse Angular CDK primitives (Listbox, Menu, Dialog, Overlay, Tree, A11y `LiveAnnouncer`/`FocusTrap`) rather than re-implementing ARIA wiring.
+- Style ARIA state attributes rather than toggling presentation classes:
+
+```css
+[aria-selected="true"] { background: var(--color-selected); }
+[aria-disabled="true"] { opacity: 0.5; cursor: not-allowed; }
+```
+
+## Anti-patterns to refuse
+
+- `HttpClient` injected into a presentational component.
+- Subscriptions in components without `takeUntilDestroyed` (or a documented manual `ngOnDestroy` cleanup).
+- `canActivate` on a route whose entire chunk should be withheld from unauthorized users — use `canMatch`.
+- Class-based `HTTP_INTERCEPTORS` providers on a standalone-first project.
+- Manual `subscribe()` + assign-to-property to flow Observable data into the view when `async` pipe or `toSignal` covers the use case.
+
+## Evidence
+
+- Targeted tests for the changed behavior (see `rules/angular/testing.md`).
+- `ng lint` (or project equivalent) on touched files.
+- `ng build` to verify typed templates and route configuration compile.

package/rules/angular/project-structure.md

@@ -1,7 +1,7 @@
 ---
 name: angular-project-structure
-description: Angular workspace and project-structure standards for agents working in Angular applications.
-version: 1.0.0
+description: Concrete Angular workspace, file-naming, feature-folder, and provider-bootstrapping standards for agents working in Angular applications.
+version: 1.1.0
 required: false
 category: angular
 tools:
@@ -13,33 +13,125 @@ source_urls:
   - https://angular.dev/style-guide
   - https://angular.dev/tools/cli
   - https://angular.dev/reference/configs/workspace-config
+  - https://angular.dev/guide/ngmodules/standalone
 applies_to:
   - angular.json
   - package.json
+  - src/main.ts
   - src/app/**/*.ts
   - src/app/**/*.html
 ---
 
 # Angular Project Structure Rules
 
-**Load when:** The project contains `angular.json` or `@angular/core`, or the task touches Angular app structure, routes, components, services, templates, or tests.
+**Load when:** The project contains `angular.json` or `@angular/core`, or the task touches Angular app structure, routes, file layout, providers, or bootstrap configuration.
 
-## Sources
+## Version Awareness
+
+Confirm the Angular version (`ng version` or `package.json`) before suggesting structure. Standalone APIs and the v17+ application builder are now defaults; do not invent NgModules on a standalone-first project, and do not migrate a working NgModule layout as a side effect of an unrelated change.
 
-Track source material explicitly so future updates can verify whether the rule is stale:
+## Sources
 
 - Angular Style Guide — https://angular.dev/style-guide
 - Angular CLI Overview — https://angular.dev/tools/cli
 - Angular Workspace Configuration — https://angular.dev/reference/configs/workspace-config
+- Standalone APIs — https://angular.dev/guide/ngmodules/standalone
 
 ## Rules
 
-- Prefer Angular CLI-generated structure and names unless the project already has a stronger local convention.
-- Keep related files together by feature or component. Do not create broad catch-all folders for unrelated utilities.
-- Keep Angular-specific code under the existing app/source root; do not introduce a parallel structure unless project evidence requires it.
-- Follow existing project routing, state-management, and shared-library boundaries before adding new locations.
-- Treat `angular.json`, builder targets, and TypeScript config edits as project-wide changes. Keep them narrow and verify with the relevant configured Angular command.
-- Do not add framework rules from another ecosystem, such as React or Vue, to Angular-only work.
+### File and folder naming
+
+Follow Angular CLI conventions — one artifact per file. Use kebab-case file names and PascalCase class names:
+
+- `user-profile.component.ts` + `user-profile.component.html` + `user-profile.component.scss` + `user-profile.component.spec.ts`
+- `user.service.ts`, `auth.guard.ts`, `date-format.pipe.ts`, `logging.interceptor.ts`, `user.resolver.ts`
+- Test files live next to the unit they test, named `<name>.spec.ts`.
+- Generate scaffolding with the CLI rather than handwriting it: `ng generate component features/users/user-card --change-detection=OnPush --inline-style=false`.
+
+### Feature folders
+
+Group by feature, then by artifact. Do not create catch-all `shared/` or `utils/` buckets for unrelated code.
+
+```
+src/app/
+  core/                 # app-wide singletons: auth, http interceptors, app-level guards
+  shared/               # reusable presentational components, pipes, directives
+  features/
+    users/
+      users.routes.ts
+      user-list/
+        user-list.component.{ts,html,scss,spec.ts}
+      user-detail/
+        user-detail.component.{ts,html,scss,spec.ts}
+      user.service.ts
+      user.model.ts
+    auth/
+      auth.routes.ts
+      ...
+  app.config.ts         # application providers (router, http, etc.)
+  app.routes.ts         # top-level routes
+  app.component.ts      # root component
+```
+
+- Keep route configuration co-located with the feature it serves (`users.routes.ts`), and lazy-load via `loadChildren`.
+- Place app-wide providers (`provideRouter`, `provideHttpClient`, interceptors, error handlers) in `app.config.ts`. Bootstrap from `main.ts` with `bootstrapApplication(AppComponent, appConfig)`.
+- A new directory or top-level folder must be justified by existing project evidence. Follow project routing, state-management, and shared-library boundaries before adding new locations.
+
+### Standalone bootstrap
+
+```typescript
+// main.ts
+bootstrapApplication(AppComponent, appConfig).catch(console.error);
+
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes, withComponentInputBinding(), withViewTransitions()),
+    provideHttpClient(withInterceptors([authInterceptor, errorInterceptor])),
+    provideAnimationsAsync(),
+  ],
+};
+```
+
+- Use functional providers (`provideRouter`, `provideHttpClient`, `provideAnimationsAsync`) over the legacy module forms on standalone-first projects.
+- Register HTTP interceptors functionally via `withInterceptors([...])`. Class-based `HTTP_INTERCEPTORS` multi-providers are reserved for NgModule-centered projects.
+
+### Routing layout
+
+```typescript
+// app.routes.ts
+export const routes: Routes = [
+  { path: '', pathMatch: 'full', redirectTo: 'home' },
+  { path: 'home', loadComponent: () => import('./features/home/home.component').then(m => m.HomeComponent) },
+  {
+    path: 'users',
+    loadChildren: () => import('./features/users/users.routes').then(m => m.USERS_ROUTES),
+  },
+  { path: '**', loadComponent: () => import('./shared/not-found/not-found.component').then(m => m.NotFoundComponent) },
+];
+```
+
+- Lazy-load every feature area with `loadChildren` (or `loadComponent` for a single route). Eagerly loading feature trees inflates the initial bundle.
+- Use `withComponentInputBinding()` so route params and query params bind to component `input()` signals automatically.
+- Put guards/resolvers next to the route file (`users.guards.ts`, `user.resolver.ts`), not in a global `guards/` bucket.
+
+### Workspace and config files
+
+- Treat `angular.json`, `tsconfig*.json`, builder targets, and `package.json` script changes as project-wide changes. Keep edits narrow and verify with the configured command (`ng build`, `ng test`, `ng lint`).
+- Do not switch the application builder, change `target`/`module` settings, or rename top-level paths casually — those are coordinated migrations.
+- `environments/environment*.ts` files describe configuration shape, not real secrets. Inject production secrets via CI/CD, not source.
+
+### Cross-ecosystem hygiene
+
+- Do not add React, Vue, or other-framework conventions to an Angular project. If shared code must straddle frameworks, isolate it behind a framework-neutral library.
+- Match the project's existing module system (ESM vs CommonJS) and import style. Use path aliases from `tsconfig.json` where the project already defines them.
+
+## Anti-patterns to refuse
+
+- A single `shared/` directory accumulating unrelated services, pipes, components, and constants.
+- New NgModules created on a standalone-first project just to host providers — use `app.config.ts` or route-level `providers`.
+- Eagerly importing feature components into `app.routes.ts` instead of `loadChildren` / `loadComponent`.
+- Editing `angular.json` builders, `tsconfig` paths, or `package.json` scripts as part of an unrelated component or service change.
 
 ## Evidence
 

package/rules/angular/security.md

@@ -0,0 +1,152 @@
+---
+name: angular-security
+description: Concrete Angular security rules — XSS prevention, HttpClient discipline, secret handling, route guards, and SSR safety.
+version: 1.0.0
+required: false
+category: angular
+tools:
+  - claude
+  - copilot
+  - codex
+  - cursor
+source_urls:
+  - https://angular.dev/best-practices/security
+  - https://angular.dev/api/platform-browser/DomSanitizer
+  - https://angular.dev/guide/http/security
+  - https://angular.dev/guide/ssr
+applies_to:
+  - src/app/**/*.component.ts
+  - src/app/**/*.component.html
+  - src/app/**/*.service.ts
+  - src/app/**/*.interceptor.ts
+  - src/app/**/*.guard.ts
+  - src/app/**/*.routes.ts
+  - src/environments/**/*.ts
+  - src/**/*.server.ts
+  - server.ts
+---
+
+# Angular Security Rules
+
+**Load when:** Touching code that handles user input, renders untrusted HTML, calls external APIs, manages auth/tokens, configures route guards, or runs under SSR.
+
+## Version Awareness
+
+Sanitization, route guard, and SSR APIs evolve between versions — verify the version with `ng version` before suggesting an API. Do not introduce APIs that don't exist in the project's Angular version, and do not rip out a guard or sanitization step as a side effect of an unrelated change.
+
+## Sources
+
+- Angular Security Best Practices — https://angular.dev/best-practices/security
+- DomSanitizer API — https://angular.dev/api/platform-browser/DomSanitizer
+- HttpClient Security — https://angular.dev/guide/http/security
+- Angular SSR Guide — https://angular.dev/guide/ssr
+
+## Rules
+
+### XSS prevention
+
+Angular auto-sanitizes interpolation and property bindings. Do not bypass the sanitizer with user-controlled input.
+
+```typescript
+// WRONG — bypasses sanitization, classic XSS
+this.safeHtml = this.sanitizer.bypassSecurityTrustHtml(userInput);
+
+// CORRECT — explicit sanitization, returns string with dangerous content stripped
+this.safeHtml = this.sanitizer.sanitize(SecurityContext.HTML, userInput);
+```
+
+- Never call `bypassSecurityTrustHtml` / `bypassSecurityTrustScript` / `bypassSecurityTrustStyle` / `bypassSecurityTrustUrl` / `bypassSecurityTrustResourceUrl` on user-controlled input. If you must bypass, the source must be a static, trusted constant, with a comment explaining why.
+- Avoid `[innerHTML]` for untrusted content. Use `{{ value }}` interpolation or `[innerText]` for plain text. If rich content is required, render it through a sanitizing pipe.
+- Never bind `[href]` or `[src]` directly to user-provided URLs without scheme validation — Angular sanitizes some URL contexts but not all.
+- Never build templates by string concatenation with user data.
+
+### HttpClient discipline
+
+Use `HttpClient` exclusively — not raw `fetch()` or `XHR` — so interceptors (auth headers, error mapping, retry, logging) apply uniformly.
+
+```typescript
+// WRONG — bypasses interceptors entirely
+const res = await fetch('/api/users');
+
+// CORRECT
+users$ = this.http.get<User[]>('/api/users');
+```
+
+- Attach auth tokens via an interceptor, never by hand on every call. One source of truth for `Authorization` headers.
+- Type and validate API responses. Treat external data as `unknown` at the boundary and narrow with a schema (Zod / io-ts / hand-rolled guard) before letting it flow into typed signals or components.
+- Never log full HTTP responses that may contain tokens, PII, or credentials. Redact before logging.
+- For SSR fetches, prefer relative URLs (or the configured base URL) so the server doesn't re-hit the public host.
+
+### Secret and config management
+
+```typescript
+// WRONG — hardcoded secret in source
+const apiKey = 'sk-live-xxxxxxxxxxxxxxxxxxxxxxxx';
+
+// CORRECT — env config shape, real value injected by CI/CD
+import { environment } from '../environments/environment';
+const apiKey = environment.apiKey;
+```
+
+- Treat `environments/environment*.ts` as configuration shape, not as a place to commit production secrets. Real secrets come from CI/CD env vars or a secret manager.
+- Do not introduce `process.env.*` reads into browser-bound code unless the build pipeline is configured to inline them safely.
+- Never commit `.env` files containing real credentials.
+
+### Route guards
+
+Every authenticated or role-restricted route must have a guard. Hiding a UI element is not access control.
+
+```typescript
+{
+  path: 'admin',
+  canMatch: [authGuard, roleGuard('admin')],
+  loadChildren: () => import('./admin/admin.routes').then(m => m.ADMIN_ROUTES),
+}
+```
+
+- Use `canMatch` for sensitive routes so the route's lazy chunk is not loaded at all for unauthorized users.
+- Use `canDeactivate` to prevent accidental data loss on unsaved forms — but never as a security mechanism.
+- Guards must trust a server-side check too. The server is the security boundary; the client guard is a UX gate.
+
+### Auth tokens
+
+- Store tokens in HTTP-only cookies when the backend supports it. If using `localStorage` / `sessionStorage`, accept the XSS risk and mitigate accordingly.
+- Refresh tokens belong in HTTP-only cookies or a dedicated secure storage layer — never in plain `localStorage`.
+- Clear all auth state on logout, including in-memory signals, interceptors caches, and storage.
+
+### SSR safety
+
+When the app runs under Angular SSR:
+
+- Never access `window`, `document`, `localStorage`, `sessionStorage`, or `navigator` directly. Gate browser-only code with `isPlatformBrowser(this.platformId)` or inject the `DOCUMENT` token for DOM access.
+- Sanitize user input on the server too — DOM-based XSS is reachable through SSR'd markup.
+- Do not place server-only secrets into `TransferState` — anything serialized there ships to the client.
+- Watch for hydration mismatches: server-rendered markup must equal initial client render. Diverging output is both a bug and a possible injection vector.
+
+### Content Security Policy
+
+Configure CSP headers server-side. Specifically:
+
+- Avoid `unsafe-inline` in `script-src`. If SSR emits inline state, use Angular's CSP nonce support and propagate the nonce on every inline tag.
+- Avoid `unsafe-eval` — Angular AOT does not need it.
+- Restrict `connect-src` to the API origins the app actually uses.
+
+### Dependencies
+
+- Treat `npm audit` / `pnpm audit` / `yarn audit` findings as real signals. Resolve high-severity issues before shipping touched code paths.
+- Do not pin to versions with known active CVEs as a workaround for a feature change.
+
+## Anti-patterns to refuse
+
+- `bypassSecurityTrust*` on a value derived in any way from user input.
+- `[innerHTML]` bound to a request body, query param, or form value without sanitization.
+- `fetch('/api/...')` in a service that already has `HttpClient` available.
+- Auth checks done only by hiding a button — no guard, no server-side check.
+- `window.localStorage.getItem(...)` in code that also runs under SSR.
+
+## Evidence
+
+- For changes that affect rendering of untrusted content: a test asserting the rendered output does not contain the dangerous payload.
+- For auth/guard changes: a `RouterTestingHarness` test that exercises both allowed and denied branches.
+- For interceptor changes: a `HttpTestingController` test confirming the header / retry / error mapping behavior.
+- For dependency upgrades touching security: the audit report after the change.