@tungvivas/angular-vibe-kit 0.1.0

package/practices/v20plus.md

@@ -0,0 +1,210 @@
+# Angular Best Practices — v20+ (Signal-Native Era)
+
+> Framework-level patterns only. This file describes HOW to write idiomatic
+> Angular 20+ — syntax, DI, components, Signals. It does NOT dictate folder
+> structure, state-management choice, or naming — those are project decisions
+> recorded in `.claude/rules/project-rules.md` (inferred from the codebase).
+>
+> When the project already follows a correct pattern, follow the project.
+> When it is below standard, apply this standard to NEW code only.
+
+---
+
+## Module System
+- **Standalone is implicit** — `standalone: true` no longer needs to be written.
+  Components, directives, and pipes are standalone by default.
+- Bootstrap: `bootstrapApplication(AppComponent, appConfig)`.
+- Providers in `app.config.ts` (`provideRouter`, `provideHttpClient`, etc.).
+- NgModules are fully legacy — do NOT add new ones.
+
+## Component Pattern
+- `ChangeDetectionStrategy.OnPush` everywhere — or **zoneless** (see below).
+- **Signal-based APIs are the default** for all inputs, outputs, queries:
+
+```typescript
+@Component({
+  selector: 'app-user-card',
+  imports: [DatePipe],
+  templateUrl: './user-card.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class UserCardComponent {
+  // Signal inputs (replaces @Input)
+  user = input.required<User>();
+  showActions = input(true);           // with default
+
+  // Two-way binding (replaces @Input + @Output pair)
+  selectedId = model<number | null>(null);
+
+  // Signal output (replaces @Output + EventEmitter)
+  delete = output<number>();
+
+  // Signal queries (replaces @ViewChild / @ContentChild)
+  tableRef = viewChild<ElementRef>('table');
+
+  // Derived state
+  displayName = computed(() => `${this.user().name} (${this.user().email})`);
+
+  onDeleteClick(): void {
+    this.delete.emit(this.user().id);
+  }
+}
+```
+
+- `@Input()` / `@Output()` / `@ViewChild()` still work but are legacy — use signal APIs for all new code.
+
+## Template Syntax
+- `@if`, `@else`, `@for` (required `track`), `@switch`, `@defer`, `@empty`, `@placeholder`.
+- **`@let`** — declare template-local variables (stable since v18.1):
+
+```html
+@let user = currentUser();
+@let greeting = 'Hello, ' + user.name;
+
+<h1>{{ greeting }}</h1>
+
+@if (isLoading()) {
+  <app-spinner />
+} @else {
+  @for (item of items(); track item.id) {
+    <app-item-card [item]="item" />
+  } @empty {
+    <app-empty-state />
+  }
+}
+
+@defer (on viewport) {
+  <app-heavy-chart [data]="chartData()" />
+} @placeholder {
+  <div class="chart-skeleton" />
+}
+```
+
+## Services & Dependency Injection
+- `inject()` everywhere — no constructor injection.
+- `@Injectable({ providedIn: 'root' })` for singletons.
+- HttpClient ONLY in services; services return `Observable<T>` or use `resource()`.
+
+## HTTP
+- `provideHttpClient(withInterceptors([...]))` with functional interceptors.
+- **`httpResource()`** for declarative GET requests tied to signals — ⚠️ **experimental in v20** (ready to try, API may change). Use only if the team accepts experimental APIs; otherwise stick to plain HttpClient:
+
+```typescript
+// Declarative: auto-refetches when userId signal changes (experimental API)
+readonly userResource = httpResource<User>(
+  () => `/api/users/${this.userId()}`
+);
+// userResource.value() → User | undefined
+// userResource.isLoading() → boolean
+// userResource.error() → unknown
+```
+
+- Plain `HttpClient` + `Observable` for mutations (POST/PUT/DELETE) and complex flows.
+- Functional interceptors:
+
+```typescript
+export const authInterceptor: HttpInterceptorFn = (req, next) => {
+  const token = inject(AuthService).accessToken();
+  return token
+    ? next(req.clone({ setHeaders: { Authorization: `Bearer ${token}` } }))
+    : next(req);
+};
+```
+
+## Routing
+- `loadComponent()` / `loadChildren()` for lazy loading.
+- Functional guards (`CanActivateFn`) and resolvers (`ResolveFn`).
+- **Route-level render mode** (SSR): configure per-route in `app.routes.ts` when using SSR.
+
+## Reactive / Signals (signal-native)
+
+Signal primitives:
+| API | Purpose | Status (v20) |
+|-----|---------|--------------|
+| `signal(val)` | Writable state | Stable |
+| `computed(() => ...)` | Derived state (memoized) | Stable |
+| `effect(() => ...)` | Side effects when signals change | Stable |
+| `linkedSignal(() => ...)` | Writable signal derived from another | Stable (graduated in v20) |
+| `resource()` / `rxResource()` | Async state (loading/error/value) | ⚠️ Experimental |
+| `httpResource()` | HTTP GET tied to signals | ⚠️ Experimental |
+| `toSignal(obs$)` | Bridge Observable → Signal | Stable |
+| `toObservable(sig)` | Bridge Signal → Observable | Stable |
+
+Rules:
+- `computed()` for all derived state — never store redundant computed data in a separate signal.
+- `effect()` only for side effects (logging, DOM, third-party libs) — NOT for updating other signals (use `computed` or `linkedSignal` instead). In v20, signal writes inside `effect()` are allowed by default (no `allowSignalWrites`).
+- `resource()` / `rxResource()` / `httpResource()` are **experimental** — use for async data only if the team accepts experimental APIs; otherwise use plain HttpClient + Observable. Use plain HttpClient for all mutations regardless.
+- Subscriptions (when still needed): `takeUntilDestroyed(inject(DestroyRef))`.
+
+```typescript
+export class UserListComponent {
+  private userService = inject(UserService);
+  private destroyRef = inject(DestroyRef);
+
+  // Filter signal drives the resource
+  filter = signal('');
+  page = signal(1);
+
+  usersResource = httpResource<PaginationResponse<User>>(
+    () => `/api/users?page=${this.page()}&search=${this.filter()}`
+  );
+
+  userCount = computed(() => this.usersResource.value()?.meta.total ?? 0);
+}
+```
+
+## Zoneless Change Detection (stable in v20)
+- New projects: configure with `provideZonelessChangeDetection()` in `app.config.ts`.
+- Existing projects migrating: replace `provideZoneChangeDetection` carefully — test thoroughly.
+- In zoneless mode: CD is driven entirely by signals and `markForCheck()`. NEVER rely on `setTimeout`, `Promise.then`, or other macrotask-based CD triggers.
+- `async` pipe still works in zoneless mode.
+
+```typescript
+// app.config.ts — zoneless
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideZonelessChangeDetection(),
+    provideRouter(routes),
+    provideHttpClient(withInterceptors([authInterceptor])),
+  ],
+};
+```
+
+## Forms
+- Reactive Forms (`NonNullableFormBuilder`) for all validated forms.
+- **Signal-based forms** (developer preview in v20) — use only if the team opts in explicitly.
+- Show validation messages when control is `touched` and `invalid`.
+
+## TypeScript
+- No `any`. Signal types are inferred — do not add redundant annotations.
+- `interface` for object shapes, `type` for unions/mapped types.
+- `readonly` on arrays and objects that must not be mutated.
+
+## Testing
+- Unit (service): `provideHttpClientTesting()` + `HttpTestingController`.
+- Component: `TestBed` + mock services; assert signal values with `TestBed.flushEffects()` where needed.
+- E2E: Playwright.
+- Runner: Jest or Web Test Runner / Vitest (Karma is legacy — check what the project uses).
+
+## Security
+- Tokens in memory (signal in service) or httpOnly cookie — NOT localStorage.
+- No hardcoded backend URL — use `environment`.
+- Route guards for all auth-required routes.
+
+---
+
+## What's New vs v18-19
+
+| Feature | v18-19 | v20+ |
+|---------|--------|------|
+| Signal inputs/outputs | Production-ready (v19) | Default; `@Input`/`@Output` legacy |
+| Signals core (`signal`/`effect`/`linkedSignal`) | Stable/preview mix | **All graduated to stable** |
+| `linkedSignal()` | Experimental (v19) | **Stable** |
+| `httpResource()` / `resource()` / `rxResource()` | Experimental (v19.2+) | ⚠️ **Still experimental** |
+| Zoneless CD | Experimental (`provideExperimentalZonelessChangeDetection`) | **Stable** (`provideZonelessChangeDetection`) |
+| `effect()` signal writes | Needed `allowSignalWrites` | **Allowed by default** |
+| Incremental hydration (`@defer`-powered) | Developer preview (since v17) | **Stable** |
+| Signal-based forms | — | Experimental / developer preview |
+| `@let` template variables | Stable (since v18.1) | Stable |
+| `standalone: true` | Implicit default since **v19** | Implicit default (carried over) |
+| Route-level render mode (SSR) | Preview | **Stable** |

package/templates/CLAUDE.md

@@ -0,0 +1,55 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with code in this repository.
+
+> Generated by `angular-vibe-kit`. Run `/init` to populate this file from your codebase.
+> Keep under 200 lines — link out to docs/ for details.
+
+## Read first
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — layers, routing, state, request flow
+- [docs/API_CONTRACT.md](docs/API_CONTRACT.md) — endpoints the frontend calls + payload shapes
+- [docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md) — UI library, theme, shared components
+- [docs/PROJECT-STATUS.md](docs/PROJECT-STATUS.md) — current progress, next tasks, warnings
+- `.claude/angular-practices/` — Angular version idioms for this project (auto-detected)
+- Feature `CONTEXT.md` files when modifying a specific feature
+
+## Common commands
+> Run `/init` — this section will be populated with commands from your package.json.
+
+```bash
+# Run dev server
+ng serve
+
+# Build production
+ng build --configuration production
+
+# Unit tests
+ng test    # or: jest
+
+# E2E tests
+npx playwright test
+
+# Lint + type check
+ng lint
+npx tsc --noEmit
+```
+
+## Runtime and tooling
+> Run `/init` — this section will be populated with your detected stack.
+
+- Angular version: {{detected by /init}}
+- State management: {{detected by /init}}
+- UI library: {{detected by /init}}
+- Test runner: {{detected by /init}}
+
+## High-level architecture
+> Run `/init` — this section will summarize your detected architecture.
+> Full details in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+
+## When updating docs
+If behavior changes, update the related docs in the same commit:
+- `docs/PROJECT-STATUS.md` for session progress
+- `docs/API_CONTRACT.md` for endpoint changes
+- `docs/DESIGN_SYSTEM.md` for UI/token changes
+- Feature `CONTEXT.md` for non-obvious module behavior
+- `docs/decisions/` for meaningful architectural decisions

package/templates/docs/API_CONTRACT.md

@@ -0,0 +1,46 @@
+# API Contract
+
+> Endpoints the frontend calls, mapped to Angular services.
+> Run `/init` to populate from existing service files.
+> Update whenever a service starts calling a new/changed endpoint.
+
+## Base URL
+```
+Development: {{from environment.ts}}
+Production:  {{from environment.prod.ts}}
+```
+
+## Response Envelope
+```typescript
+interface ApiResponse<T> {
+  statusCode: number;
+  data: T;
+  message: string;
+}
+
+interface PaginationResponse<T> {
+  meta: { page: number; pageSize: number; pages: number; total: number };
+  result: T[];
+}
+```
+
+## Auth
+All endpoints require `Authorization: Bearer <accessToken>` except those marked **Public**.
+
+---
+
+## {{Feature}} — `{{Feature}}Service`
+
+| Method | Endpoint | Service method |
+|--------|----------|----------------|
+| GET | `/{{path}}?page=&size=` | `getAll(params)` |
+| GET | `/{{path}}/:id` | `getById(id)` |
+| POST | `/{{path}}` | `create(payload)` |
+| PUT | `/{{path}}/:id` | `update(id, payload)` |
+| DELETE | `/{{path}}/:id` | `delete(id)` |
+
+```typescript
+interface {{Feature}} { /* mirror backend DTO */ }
+interface Create{{Feature}}Request { /* ... */ }
+interface Update{{Feature}}Request { /* ... */ }
+```

package/templates/docs/ARCHITECTURE.md

@@ -0,0 +1,27 @@
+# Architecture
+
+> Run `/init` to populate this file from your codebase.
+
+## Overview
+{{What this app is, who uses it, which backend it talks to.}}
+
+## Layers
+- **core/** — singleton services, HTTP interceptors (auth, error), guards, layout
+- **shared/** — reusable presentational components, pipes, directives
+- **features/** — business modules (model, service, pages, components)
+
+## Routing & Lazy Loading
+{{Route tree, public vs protected routes, lazy loading strategy.}}
+
+## State Management
+{{Which approach (Signals / NgRx / BehaviorSubject) and the decision rule.}}
+
+## HTTP & Error Flow
+1. Smart component calls a feature service
+2. Service issues `HttpClient` request → `Observable<ApiResponse<T>>`
+3. Auth interceptor attaches `Authorization: Bearer <token>`
+4. Error interceptor handles 401 (refresh/redirect) and maps errors
+5. Component renders loading / error / empty / data
+
+## Auth
+{{Token storage strategy (memory / httpOnly cookie), refresh flow.}}

package/templates/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,27 @@
+# Design System
+
+> Run `/init` to populate from your project's styles and UI library config.
+
+## UI Library
+{{Angular Material / PrimeNG / Tailwind / custom}}
+
+## Design Tokens
+| Token | Value |
+|-------|-------|
+| Primary | {{e.g. #2563eb}} |
+| Danger | {{...}} |
+| Spacing scale | {{4 / 8 / 12 / 16 / 24 / 32}} |
+| Breakpoints | {{mobile 375 / tablet 768 / desktop 1280}} |
+
+## Shared Components
+| Component | Role |
+|-----------|------|
+| Spinner | Loading indicator |
+| EmptyState | No data message |
+| ErrorMessage | Error display |
+| ConfirmDialog | Confirmation modal |
+
+## Rules
+- Every page must handle loading / error / empty states
+- Use design tokens, not hardcoded values
+- New shared UI goes in `shared/` only if used by 2+ features

package/templates/docs/PROJECT-STATUS.md

@@ -0,0 +1,19 @@
+# Project Status
+
+> Date: {{YYYY-MM-DD}} | Session: 1
+> Run `/init` to populate from the existing codebase.
+
+## Completed
+- {{Features/modules already in the codebase}}
+
+## In Progress
+- {{none}}
+
+## Next Tasks
+1. {{...}}
+
+## Deferred Issues
+- [P2] {{...}}
+
+## Warnings
+- ⚠️ {{Known gotchas future sessions must know}}

package/templates/docs/decisions/001-state-management.md

@@ -0,0 +1,18 @@
+# ADR 001: State Management Strategy
+
+> Status: Accepted | Date: {{YYYY-MM-DD}}
+
+## Context
+{{Why a state decision is needed; what kinds of state the app has.}}
+
+## Options Considered
+- **Signals + services** — Angular-native, minimal boilerplate (v16+)
+- **NgRx Store** — Redux, DevTools, more boilerplate
+- **Service + BehaviorSubject** — traditional RxJS
+
+## Decision
+{{Which option. Rule for when to use what.}}
+
+## Consequences
+- Positive: {{...}}
+- Trade-offs: {{...}}

package/templates/docs/decisions/002-auth-token-storage.md

@@ -0,0 +1,19 @@
+# ADR 002: Auth Token Storage & Refresh
+
+> Status: Accepted | Date: {{YYYY-MM-DD}}
+
+## Context
+{{JWT auth. Token storage has security implications (XSS vs CSRF).}}
+
+## Options Considered
+- **In-memory** — safest vs XSS; lost on page refresh
+- **httpOnly cookie (refresh token)** — not JS-readable, pairs with in-memory access token
+- **localStorage** — vulnerable to XSS; avoid for tokens
+
+## Decision
+{{Access token in memory. Refresh token in httpOnly cookie.
+401 → interceptor calls /auth/refresh → retry original request → on failure logout.}}
+
+## Implementation Pointers
+- Auth interceptor: `core/.../auth.interceptor.ts`
+- Token state: `core/auth/auth.service.ts`

package/templates/rules/project-rules.md

@@ -0,0 +1,72 @@
+# Project Rules — Angular
+
+> Auto-loaded by Claude Code every session (this file lives in .claude/rules/).
+> Generated by `angular-vibe-kit /init`. Keep this file focused on RULES — not explanations.
+> Full architecture context is in docs/ARCHITECTURE.md.
+
+> Run `/init` to populate this file with rules inferred from your codebase.
+
+---
+
+## ⚖️ Precedence — which rule wins (read this first)
+
+When guidance conflicts, follow this order top to bottom:
+
+1. **This project's conventions (this file + the codebase)** — HIGHEST.
+   For legitimate project choices, the codebase wins even if it differs from the
+   Angular best-practice profile. This covers: folder layout & naming, state
+   management choice, API/response shape, auth model, forms library, HTTP client.
+   *If the project does it consistently and it works, match it.*
+
+2. **Angular best-practice profile** (`.claude/angular-practices/<version>.md`) —
+   applies when the project has NO established convention, OR when the existing code
+   is objectively below standard (e.g. `any`, HTTP in components, logic in templates,
+   missing subscription teardown). In those cases the standard applies to **NEW CODE ONLY**.
+
+3. **Legacy modules** (listed in Coexistence Strategy below) — **never refactored**
+   to satisfy 1 or 2, regardless. Touch only when a task explicitly targets them.
+
+> "Below standard" vs "valid project choice": a *valid choice* is a coherent decision
+> with no objective defect (naming, structure, library). *Below standard* is an
+> objective defect the best-practice profile flags. When unsure which one applies, ASK.
+
+---
+
+## Tech Stack
+> /init will fill this in from package.json + src/ scan.
+
+## Folder Structure
+> /init will describe the actual layout found in src/.
+
+## Naming Conventions
+| Type | Pattern | Example |
+|------|---------|---------|
+| Component | `kebab-case.component.ts` | `user-list.component.ts` |
+| Service | `kebab-case.service.ts` | `user.service.ts` |
+| Model/Interface | `PascalCase` | `User`, `ApiResponse<T>` |
+| Routes file | `kebab-case.routes.ts` | `user.routes.ts` |
+
+## Coding Rules
+> /init will generate concrete rules based on Angular version + what the project does.
+
+## DO NOT
+- Do NOT use `any`
+- Do NOT call HttpClient from components
+- Do NOT store tokens in localStorage
+- Do NOT hardcode the backend URL
+
+## Reference Examples
+> /init fills this with the best existing files to copy patterns from.
+> `/new-feature` opens these and mirrors their style.
+
+| Kind | File | Why it's the reference |
+|------|------|------------------------|
+| Service | {{path}} | {{reason}} |
+| Smart / page component | {{path}} | {{reason}} |
+| Dumb / presentational component | {{path}} | {{reason}} |
+| Test spec | {{path}} | {{reason}} |
+
+## Coexistence Strategy
+> /init will classify existing code as standard / below-standard and generate:
+> - Rules for new code
+> - List of legacy modules to leave untouched