devendra-skill-package 1.0.2

package/.github/skills/clean-architecture-generator/references/platform-angular.md

@@ -0,0 +1,374 @@
+# Platform File — Angular
+
+Read `architecture-core.md` first. Angular differs from the React-family platforms in one
+structural way that changes how DI is implemented: **Angular has a built-in, framework-native
+dependency injection system.** The manual "DI Pattern A / Pattern B" containers used for React
+Native and React do not apply here — do not port them. Use Angular's own `@Injectable` /
+`providers` mechanism instead (detailed below).
+
+Everything under "Stack Fingerprint Defaults" applies **only** when Phase 1 detection found nothing
+in the target repo.
+
+---
+
+## Sub-Variant Detection (run before anything else)
+
+| Signal | Sub-variant | Affects |
+|---|---|---|
+| `src/app/app.config.ts` exists, no `app.module.ts` | Standalone components (Angular 14+) | Feature wiring goes in each component's `providers` array or `app.config.ts`; no `NgModule` is created |
+| `src/app/app.module.ts` exists | NgModule-based | Feature wiring goes in a `[Feature]Module` with a `providers` array |
+
+State the detected sub-variant before generating any file — it changes where the repository→use
+case provider mapping is registered.
+
+---
+
+## Stack Fingerprint Defaults (greenfield only)
+
+| Concern | Detect first (search for) | Default if nothing detected |
+|---|---|---|
+| Language | — | TypeScript, strict mode |
+| State management | `@ngrx/store` imports (`createReducer`, `createFeature`), `@ngrx/signals`, `@datorama/akita`, `@ngxs/store`, `signal(`/`computed(` from `@angular/core` used as app state | Plain RxJS: an injectable `[Feature]Store` service holding a `BehaviorSubject` per concern, exposed as `Observable` |
+| HTTP client | `HttpClient` from `@angular/common/http` (this is Angular's standard client — still verify it's actually imported, not a wrapped Axios instance) | `HttpClient` with a functional `HttpInterceptorFn` |
+| Storage | existing `StorageService`/`localStorage`/`sessionStorage` wrapper | injectable `StorageService` wrapping `sessionStorage` for tokens, `localStorage` for non-sensitive UI state |
+| Routing | `app.routes.ts` / `RouterModule.forRoot(` | Angular Router with lazy-loaded feature routes |
+| DI mechanism | — (Angular always has DI) | `@Injectable({ providedIn: 'root' })` for app-wide singletons, or feature-scoped providers array for feature-scoped instances |
+| Test runner | `karma.conf.js`, `jest.config.*` | Whatever the project already runs (Angular CLI defaults to Karma+Jasmine; many teams migrate to Jest) — do not silently switch an existing project's test runner |
+
+---
+
+## Folder Tree
+
+```
+src/app/
+├── app.component.ts
+├── app.config.ts              # standalone bootstrap providers (or app.module.ts if NgModule-based)
+├── app.routes.ts
+│
+├── core/                       # Infrastructure — shared by all features
+│   ├── api/
+│   │   ├── api-error-handler.ts
+│   │   ├── app-error.ts
+│   │   └── token.provider.ts   # Token getter/setter (prevents circular deps)
+│   ├── interceptors/
+│   │   ├── auth.interceptor.ts     # attaches Authorization header
+│   │   └── error.interceptor.ts    # maps HTTP errors to AppError
+│   ├── guards/
+│   │   └── auth.guard.ts           # CanActivateFn
+│   ├── storage/
+│   │   └── storage.service.ts
+│   └── logging/
+│       └── logger.service.ts
+│
+├── features/
+│   └── [feature-name]/
+│       ├── domain/               # Pure TypeScript — ZERO Angular imports
+│       │   ├── entities/
+│       │   │   └── [item].entity.ts
+│       │   ├── repositories/
+│       │   │   └── [feature].repository.ts     # abstract class — see DI section
+│       │   └── use-cases/
+│       │       └── get-[item].use-case.ts
+│       ├── data/
+│       │   ├── dtos/
+│       │   │   └── [item].dto.ts
+│       │   ├── mappers/
+│       │   │   └── [feature].mapper.ts
+│       │   └── repositories/
+│       │       └── [feature].repository.impl.ts
+│       ├── presentation/
+│       │   ├── pages/
+│       │   │   └── [feature]-page/
+│       │   │       ├── [feature]-page.component.ts
+│       │   │       ├── [feature]-page.component.html
+│       │   │       └── [feature]-page.component.scss
+│       │   ├── components/
+│       │   └── state/
+│       │       └── [feature].store.ts            # RxJS store service, or NgRx feature slice if detected
+│       ├── [feature].routes.ts
+│       └── [feature].providers.ts    # provider array wiring [Feature]Repository → [Feature]RepositoryImpl
+│
+└── shared/
+    └── ui/                     # Reusable presentational components with no feature dependency
+```
+
+---
+
+## Naming Extensions (Angular-specific — official Angular style guide, not invented)
+
+Angular's own style guide uses **kebab-case file names with a dot-separated type suffix**, and
+explicitly recommends **against** an `I`-prefix on interface/abstraction names (no Hungarian
+notation). This is different from the RN/React convention in this skill and must not be mixed in:
+
+| Artifact | Convention | Example |
+|----------|------------|---------|
+| Feature folder | kebab-case | `portfolio-summary`, `user-profile` |
+| Entity file | kebab-case + `.entity.ts` | `holding.entity.ts` (class `HoldingEntity`) |
+| Repository abstraction | kebab-case + `.repository.ts`, **no `I` prefix** | `holding.repository.ts` (abstract class `HoldingRepository`) |
+| Repository implementation | kebab-case + `.repository.impl.ts` | `holding.repository.impl.ts` (class `HoldingRepositoryImpl`) |
+| Use case file | kebab-case + `.use-case.ts` | `get-holding-summary.use-case.ts` (class `GetHoldingSummaryUseCase`) |
+| DTO file | kebab-case + `.dto.ts` | `holding-summary.dto.ts` |
+| Mapper file | kebab-case + `.mapper.ts`, function named `mapTo…` | `holding.mapper.ts` → `mapHoldingDtoToDomain` |
+| Component (page) | kebab-case + `.component.ts` | `holding-detail-page.component.ts` (class `HoldingDetailPageComponent`) |
+| Store/state service | kebab-case + `.store.ts` | `holding.store.ts` (class `HoldingStore`) |
+| Route guard | kebab-case + `.guard.ts` | `auth.guard.ts` |
+| Interceptor | kebab-case + `.interceptor.ts` | `auth.interceptor.ts` |
+| Providers file | kebab-case + `.providers.ts` | `holding.providers.ts` |
+| Test file | same base name + `.spec.ts` | `holding.repository.impl.spec.ts` |
+| Loading state | `'idle' \| 'loading' \| 'succeeded' \| 'failed'` string union | never a `boolean` |
+
+---
+
+## DI — Angular's Framework-Native Mechanism (do not use RN/React manual containers)
+
+**Why this is different:** a TypeScript `interface` has no runtime representation, so Angular's DI
+cannot inject one directly. The correct Angular idiom is to make the repository contract an
+**abstract class** (which does have a runtime token) and bind the concrete implementation to it via
+a `providers` array — this is how Angular's own documentation and the wider community express
+"interface-based DI."
+
+```ts
+// domain/repositories/[feature].repository.ts
+import { Observable } from 'rxjs';
+import type { [Item]Entity } from '../entities/[item].entity';
+
+export abstract class [Feature]Repository {
+  abstract get[Item](args: [RequestArgs]): Observable<[Item]Entity>;
+}
+```
+
+```ts
+// domain/use-cases/get-[item].use-case.ts
+import { Injectable } from '@angular/core';
+import { Observable } from 'rxjs';
+import { [Feature]Repository } from '../repositories/[feature].repository';
+import type { [Item]Entity } from '../entities/[item].entity';
+
+@Injectable()
+export class Get[Item]UseCase {
+  constructor(private readonly repository: [Feature]Repository) {}
+
+  execute(args: [RequestArgs]): Observable<[Item]Entity> {
+    return this.repository.get[Item](args);
+  }
+}
+```
+
+```ts
+// data/repositories/[feature].repository.impl.ts
+import { Injectable } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable, map } from 'rxjs';
+import { [Feature]Repository } from '../../domain/repositories/[feature].repository';
+import type { [Item]Entity } from '../../domain/entities/[item].entity';
+import type { [Item]Dto } from '../dtos/[item].dto';
+import { map[Item]DtoToDomain } from '../mappers/[feature].mapper';
+
+@Injectable()
+export class [Feature]RepositoryImpl extends [Feature]Repository {
+  constructor(private readonly http: HttpClient) { super(); }
+
+  get[Item](args: [RequestArgs]): Observable<[Item]Entity> {
+    return this.http.post<[Item]Dto>('/[endpoint]', args).pipe(map(map[Item]DtoToDomain));
+  }
+}
+```
+
+```ts
+// features/[feature-name]/[feature].providers.ts
+import type { Provider } from '@angular/core';
+import { [Feature]Repository } from './domain/repositories/[feature].repository';
+import { [Feature]RepositoryImpl } from './data/repositories/[feature].repository.impl';
+import { Get[Item]UseCase } from './domain/use-cases/get-[item].use-case';
+
+export const [FEATURE]_PROVIDERS: Provider[] = [
+  { provide: [Feature]Repository, useClass: [Feature]RepositoryImpl },
+  Get[Item]UseCase,
+];
+```
+
+Register `[FEATURE]_PROVIDERS` in exactly one place:
+- **Standalone**: the feature's routed component's `providers` array, or on the lazy route in
+  `app.routes.ts` (`{ path: '[feature]', providers: [FEATURE]_PROVIDERS], loadComponent: … }`) so
+  the providers are scoped to the feature, not app-wide.
+- **NgModule**: the feature's `[Feature]Module`'s `providers` array.
+
+**Never** add `providedIn: 'root'` to a feature-specific repository/use-case unless the feature is
+genuinely meant to be a global singleton (auth is a legitimate exception, same as in RN/React) —
+feature-scoped providers keep one feature from leaking its DI graph into another.
+
+---
+
+## State Pattern — Plain RxJS Store (default when no NgRx/Akita/Signals detected)
+
+```ts
+// presentation/state/[feature].store.ts
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable } from 'rxjs';
+import type { [Item]Entity } from '../../domain/entities/[item].entity';
+
+export type LoadingState = 'idle' | 'loading' | 'succeeded' | 'failed';
+
+interface [Feature]State {
+  data: [Item]Entity | null;
+  loading: LoadingState;
+  error: string | null;
+}
+
+const initialState: [Feature]State = { data: null, loading: 'idle', error: null };
+
+@Injectable()
+export class [Feature]Store {
+  private readonly state$ = new BehaviorSubject<[Feature]State>(initialState);
+
+  readonly data$: Observable<[Item]Entity | null> = this.state$.pipe(map(s => s.data));
+  readonly loading$: Observable<LoadingState> = this.state$.pipe(map(s => s.loading));
+  readonly error$: Observable<string | null> = this.state$.pipe(map(s => s.error));
+
+  constructor(private readonly get[Item]UseCase: Get[Item]UseCase) {}
+
+  load(args: [RequestArgs]): void {
+    this.patch({ loading: 'loading', error: null });
+    this.get[Item]UseCase.execute(args).subscribe({
+      next: (data) => this.patch({ data, loading: 'succeeded' }),
+      error: (err) => this.patch({ loading: 'failed', error: err?.message ?? 'Unknown error' }),
+    });
+  }
+
+  private patch(partial: Partial<[Feature]State>): void {
+    this.state$.next({ ...this.state$.value, ...partial });
+  }
+}
+```
+
+Register `[Feature]Store` in the same `providers` array as the repository/use case. Component
+subscribes via the `async` pipe in the template (`data$ | async`) — never a manual `.subscribe()`
+in a component without unsubscribing (see Anti-Patterns).
+
+**If NgRx (or another state library) is detected** in the target repo, use that instead — a feature
+slice/store keyed to the feature, following the same file location (`presentation/state/`), not
+this BehaviorSubject pattern. Do not introduce a second state-management library alongside an
+existing one.
+
+## HTTP Interceptor Pattern
+
+```ts
+// core/interceptors/auth.interceptor.ts
+import type { HttpInterceptorFn } from '@angular/common/http';
+import { getToken } from '../api/token.provider';
+
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = getToken();
+  if (!token) return next(req);
+  return next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }));
+};
+```
+
+Register in `app.config.ts`: `provideHttpClient(withInterceptors([authInterceptor, errorInterceptor]))`.
+
+## Route Guard Pattern
+
+```ts
+// core/guards/auth.guard.ts
+import type { CanActivateFn } from '@angular/router';
+import { inject } from '@angular/core';
+import { Router } from '@angular/router';
+import { AuthTokenStore } from '../../features/auth/presentation/state/auth-token.store';
+
+export const authGuard: CanActivateFn = () => {
+  const hasToken = !!inject(AuthTokenStore).getToken();
+  if (hasToken) return true;
+  inject(Router).navigate(['/login']);
+  return false;
+};
+```
+
+## Route Definition Pattern
+
+```ts
+// features/[feature-name]/[feature].routes.ts
+import type { Routes } from '@angular/router';
+import { [FEATURE]_PROVIDERS } from './[feature].providers';
+
+export const [FEATURE]_ROUTES: Routes = [
+  {
+    path: '',
+    providers: [FEATURE]_PROVIDERS,
+    children: [
+      { path: '', loadComponent: () => import('./presentation/pages/[feature]-page/[feature]-page.component').then(m => m.[Feature]PageComponent) },
+      { path: ':id', loadComponent: () => import('./presentation/pages/[feature]-detail-page/[feature]-detail-page.component').then(m => m.[Feature]DetailPageComponent) },
+    ],
+  },
+];
+```
+
+Mount with `{ path: '[feature]', loadChildren: () => import('./features/[feature-name]/[feature].routes').then(m => m.[FEATURE]_ROUTES) }` in the parent `app.routes.ts`.
+
+## Domain / Data Layer Patterns
+
+See the DI section above — the abstract-class repository and its implementation together constitute
+both the domain contract and the data-layer implementation pattern for Angular.
+
+---
+
+## Security Rules (Angular/browser-specific — on top of architecture-core.md)
+
+1. There is no OS Keychain in a browser. Prefer an httpOnly cookie set by the server for tokens; if
+   client-side storage is required, prefer in-memory (a service field) with refresh-token rotation
+   over `localStorage`.
+2. **Never** use `localStorage` for tokens without explicitly flagging the XSS-persistence tradeoff
+   to the user — same rule as `platform-react.md`.
+3. Angular's built-in sanitization (`DomSanitizer`) protects template bindings from XSS by default —
+   **never** call `bypassSecurityTrustHtml`/`bypassSecurityTrustScript` on user-controlled content.
+
+---
+
+## Anti-Patterns (Angular-specific, on top of architecture-core.md)
+
+- **Never** try to inject a plain TypeScript `interface` — Angular's DI has no runtime token for it.
+  Use an abstract class (see DI section) or an `InjectionToken<T>` with a factory provider.
+- **Never** call `HttpClient` directly from a component — always go through the feature's
+  `[Feature]Repository` via constructor injection.
+- **Never** put business logic in a component class — it belongs in a use case.
+- **Never** subscribe to an `Observable` in a component without unsubscribing — use the `async`
+  pipe, or `takeUntilDestroyed()` (Angular 16+) if a manual subscription is unavoidable. An
+  un-unsubscribed subscription is a memory leak on every navigation away from the component.
+- **Never** register a feature's providers with `providedIn: 'root'` unless the feature is
+  genuinely meant to be a global singleton — keep feature DI scoped to the feature's route/component.
+- **Never** mix the `I`-prefix convention from `platform-react-native.md`/`platform-react.md` into
+  Angular code — Angular naming has no `I` prefix (see Naming Extensions).
+- **Never** use `any` — use a specific type or `unknown` with a type guard.
+
+---
+
+## Worked Example
+
+**Request**: "Add a watchlist feature with ability to fetch and display watchlist items."
+
+**Artifacts**:
+- Domain: `holding.entity.ts` → `WatchlistItemEntity`; `watchlist.repository.ts` (abstract class) → `WatchlistRepository`; `get-watchlist.use-case.ts` → `GetWatchlistUseCase`
+- Data: `watchlist-item.dto.ts`, `watchlist.mapper.ts` → `mapWatchlistItemDtoToDomain`, `watchlist.repository.impl.ts` → `WatchlistRepositoryImpl`
+- Presentation: `watchlist.store.ts` → `WatchlistStore`, `watchlist-page.component.ts`/`.html`/`.scss`
+- Wiring: `watchlist.providers.ts`, `watchlist.routes.ts`
+
+**Output**:
+```
+Created:
+  src/app/features/watchlist/domain/entities/watchlist-item.entity.ts
+  src/app/features/watchlist/domain/repositories/watchlist.repository.ts
+  src/app/features/watchlist/domain/use-cases/get-watchlist.use-case.ts
+  src/app/features/watchlist/data/dtos/watchlist-item.dto.ts
+  src/app/features/watchlist/data/mappers/watchlist.mapper.ts
+  src/app/features/watchlist/data/repositories/watchlist.repository.impl.ts
+  src/app/features/watchlist/presentation/state/watchlist.store.ts
+  src/app/features/watchlist/presentation/pages/watchlist-page/watchlist-page.component.ts
+  src/app/features/watchlist/presentation/pages/watchlist-page/watchlist-page.component.html
+  src/app/features/watchlist/presentation/pages/watchlist-page/watchlist-page.component.scss
+  src/app/features/watchlist/watchlist.providers.ts
+  src/app/features/watchlist/watchlist.routes.ts
+
+Updated:
+  src/app/app.routes.ts   (added lazy-loaded watchlist route)
+
+Dependency check: PASS — no layer boundary violations detected
+```