@malamute/ai-rules 1.0.0 → 1.2.0

package/configs/angular/.claude/rules/{components.md → core/components.md}

@@ -7,6 +7,59 @@ paths:
 
 # Component Rules (Angular 21)
 
+## Visibility Modifiers (MANDATORY)
+
+**Every class member MUST have an explicit visibility modifier.**
+
+```typescript
+// BAD - No visibility modifiers
+export class UserComponent {
+  store = inject(Store);
+  users = this.store.selectSignal(selectUsers);
+
+  loadUsers(): void {}
+}
+
+// GOOD - Explicit visibility on ALL members
+export class UserComponent {
+  private readonly store = inject(Store);
+
+  protected readonly users = this.store.selectSignal(selectUsers);
+
+  // Inputs/outputs are public (they are the component API)
+  public readonly name = input.required<string>();
+  public readonly userSelected = output<User>();
+
+  public loadUsers(): void {}
+
+  private formatUser(user: User): string {}
+}
+```
+
+### Visibility Rules
+
+| Visibility | When to Use |
+|------------|-------------|
+| `private` | Injected services, internal state, helper methods |
+| `protected` | State/methods needed by child classes |
+| `public` | Inputs, outputs, template-bound methods |
+| `readonly` | Injected services, signals (add with visibility) |
+
+```typescript
+// Standard pattern
+private readonly store = inject(Store);        // Service injection
+private readonly destroyRef = inject(DestroyRef);
+
+protected readonly loading = signal(false);    // Internal state
+protected readonly error = signal<string | null>(null);
+
+public readonly items = input.required<Item[]>();  // Component API
+public readonly itemSelected = output<Item>();
+
+public onItemClick(item: Item): void {}        // Template-bound
+private processItem(item: Item): void {}       // Internal helper
+```
+
 ## Code Quality
 
 ### No Useless Comments
@@ -108,15 +161,15 @@ Smart components are located in `feature/` libraries.
 export class ProductPageComponent {
   private readonly store = inject(Store);
 
-  categories = this.store.selectSignal(selectCategories);
-  filteredProducts = this.store.selectSignal(selectFilteredProducts);
-  loading = this.store.selectSignal(selectProductsLoading);
+  protected readonly categories = this.store.selectSignal(selectCategories);
+  protected readonly filteredProducts = this.store.selectSignal(selectFilteredProducts);
+  protected readonly loading = this.store.selectSignal(selectProductsLoading);
 
-  onFilterChange(filters: Filters): void {
+  public onFilterChange(filters: Filters): void {
     this.store.dispatch(ProductActions.setFilters({ filters }));
   }
 
-  onAddToCart(product: Product): void {
+  public onAddToCart(product: Product): void {
     this.store.dispatch(CartActions.addItem({ product }));
   }
 }
@@ -168,8 +221,8 @@ UI components are located in `ui/` libraries. They are purely presentational.
   changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class ProductCardComponent {
-  product = input.required<Product>();
-  addToCart = output<Product>();
+  public readonly product = input.required<Product>();
+  public readonly addToCart = output<Product>();
 }
 ```
 
@@ -191,17 +244,17 @@ Always use signal-based functions, NOT decorators:
 
 ```typescript
 // Inputs - use input(), NOT @Input()
-name = input<string>();              // Optional
-name = input('default');             // With default
-name = input.required<string>();     // Required
+public readonly name = input<string>();              // Optional
+public readonly name = input('default');             // With default
+public readonly name = input.required<string>();     // Required
 
 // Outputs - use output(), NOT @Output()
-clicked = output<void>();
-selected = output<Item>();
+public readonly clicked = output<void>();
+public readonly selected = output<Item>();
 
 // Two-way binding - use model()
-value = model<string>('');           // Optional with default
-value = model.required<string>();    // Required
+public readonly value = model<string>('');           // Optional with default
+public readonly value = model.required<string>();    // Required
 
 // Emit
 this.clicked.emit();
@@ -216,9 +269,10 @@ this.value.set('new value');         // model is writable
 @Component({
   selector: 'app-search-input',
   templateUrl: './search-input.component.html',
+  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 export class SearchInputComponent {
-  query = model('');  // Creates [(query)] binding
+  public readonly query = model('');  // Creates [(query)] binding
 }
 ```
 

package/configs/angular/.claude/rules/core/resource.md

@@ -0,0 +1,285 @@
+---
+paths:
+  - "**/*.component.ts"
+  - "**/*.store.ts"
+  - "**/services/**/*.ts"
+  - "**/data-access/**/*.ts"
+---
+
+# Angular Resource API
+
+The `resource()` and `rxResource()` APIs provide declarative data fetching with signals.
+
+## Basic Resource
+
+```typescript
+import { resource, Signal } from '@angular/core';
+
+@Component({
+  selector: 'app-user-profile',
+  template: `
+    @if (userResource.isLoading()) {
+      <app-spinner />
+    } @else if (userResource.error()) {
+      <app-error [message]="userResource.error()?.message" />
+    } @else if (userResource.hasValue()) {
+      <app-user-card [user]="userResource.value()!" />
+    }
+  `,
+})
+export class UserProfileComponent {
+  private readonly userService = inject(UserService);
+
+  public readonly userId = input.required<string>();
+
+  // Resource automatically refetches when userId changes
+  protected readonly userResource = resource({
+    request: () => this.userId(),
+    loader: ({ request: userId }) => this.userService.getById(userId),
+  });
+}
+```
+
+## Resource Properties
+
+```typescript
+const userResource = resource({
+  request: () => this.userId(),
+  loader: ({ request }) => this.userService.getById(request),
+});
+
+// Signals exposed by resource
+userResource.value();      // T | undefined - the loaded data
+userResource.isLoading();  // boolean - true while loading
+userResource.error();      // unknown | undefined - error if failed
+userResource.status();     // ResourceStatus - 'idle' | 'loading' | 'resolved' | 'error'
+
+// Type guard
+userResource.hasValue();   // boolean - true if value is available
+
+// Manual control
+userResource.reload();     // Force refetch with current request
+```
+
+## Resource with Multiple Dependencies
+
+```typescript
+@Component({ ... })
+export class ProductListComponent {
+  protected readonly category = signal<string>('all');
+  protected readonly sortBy = signal<'name' | 'price'>('name');
+  protected readonly page = signal(1);
+
+  // Refetches when ANY dependency changes
+  protected readonly productsResource = resource({
+    request: () => ({
+      category: this.category(),
+      sortBy: this.sortBy(),
+      page: this.page(),
+    }),
+    loader: ({ request }) => this.productService.search(request),
+  });
+}
+```
+
+## rxResource - RxJS Integration
+
+Use `rxResource` when your service returns Observables:
+
+```typescript
+import { rxResource } from '@angular/core/rxjs-interop';
+
+@Component({ ... })
+export class UserListComponent {
+  private readonly userService = inject(UserService);
+
+  protected readonly searchQuery = signal('');
+
+  // Works with Observable-returning services
+  protected readonly usersResource = rxResource({
+    request: () => this.searchQuery(),
+    loader: ({ request: query }) => this.userService.search(query),
+  });
+}
+```
+
+## Conditional Loading
+
+```typescript
+@Component({ ... })
+export class UserDetailComponent {
+  public readonly userId = input<string | null>(null);
+
+  protected readonly userResource = resource({
+    // Only fetch when userId is provided
+    request: () => {
+      const id = this.userId();
+      return id ? { id } : undefined;  // undefined = don't load
+    },
+    loader: ({ request }) => this.userService.getById(request.id),
+  });
+}
+```
+
+## Resource with AbortSignal
+
+Handle cancellation for long-running requests:
+
+```typescript
+protected readonly searchResource = resource({
+  request: () => this.query(),
+  loader: async ({ request, abortSignal }) => {
+    const response = await fetch(`/api/search?q=${request}`, {
+      signal: abortSignal,  // Automatically cancelled on new request
+    });
+    return response.json();
+  },
+});
+```
+
+## Local State with Resource
+
+Combine resource with local state for optimistic updates:
+
+```typescript
+@Component({ ... })
+export class TodoListComponent {
+  protected readonly todosResource = resource({
+    request: () => ({}),
+    loader: () => this.todoService.getAll(),
+  });
+
+  // Local state for optimistic updates
+  protected readonly localTodos = linkedSignal(() => this.todosResource.value() ?? []);
+
+  public async addTodo(text: string): Promise<void> {
+    const tempTodo = { id: crypto.randomUUID(), text, completed: false };
+
+    // Optimistic update
+    this.localTodos.update(todos => [...todos, tempTodo]);
+
+    try {
+      const saved = await this.todoService.create({ text });
+      // Replace temp with saved
+      this.localTodos.update(todos =>
+        todos.map(t => t.id === tempTodo.id ? saved : t)
+      );
+    } catch {
+      // Rollback on error
+      this.localTodos.update(todos =>
+        todos.filter(t => t.id !== tempTodo.id)
+      );
+    }
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+@Component({
+  template: `
+    @switch (usersResource.status()) {
+      @case ('idle') {
+        <p>Enter a search term</p>
+      }
+      @case ('loading') {
+        <app-spinner />
+      }
+      @case ('error') {
+        <div class="error">
+          <p>Failed to load users</p>
+          <button (click)="usersResource.reload()">Retry</button>
+        </div>
+      }
+      @case ('resolved') {
+        @for (user of usersResource.value(); track user.id) {
+          <app-user-card [user]="user" />
+        } @empty {
+          <p>No users found</p>
+        }
+      }
+    }
+  `,
+})
+export class UserSearchComponent {
+  protected readonly query = signal('');
+
+  protected readonly usersResource = resource({
+    request: () => {
+      const q = this.query();
+      return q.length >= 3 ? q : undefined;
+    },
+    loader: ({ request }) => this.userService.search(request),
+  });
+}
+```
+
+## Prefetching Data
+
+```typescript
+@Component({ ... })
+export class ProductPageComponent {
+  public readonly productId = input.required<string>();
+
+  // Main product data
+  protected readonly productResource = resource({
+    request: () => this.productId(),
+    loader: ({ request }) => this.productService.getById(request),
+  });
+
+  // Prefetch related products (starts loading immediately)
+  protected readonly relatedResource = resource({
+    request: () => this.productId(),
+    loader: ({ request }) => this.productService.getRelated(request),
+  });
+}
+```
+
+## Anti-patterns
+
+```typescript
+// BAD: Using resource for mutations
+const saveResource = resource({
+  request: () => this.formData(),
+  loader: ({ request }) => this.service.save(request),  // Mutating!
+});
+
+// GOOD: Use resource for reads, methods for mutations
+protected readonly userResource = resource({ ... });
+
+public async save(): Promise<void> {
+  await this.userService.save(this.formData());
+  this.userResource.reload();  // Refresh after mutation
+}
+
+
+// BAD: Not handling loading state
+@if (userResource.value()) {
+  <app-user [user]="userResource.value()!" />
+}
+// Missing loading and error states!
+
+// GOOD: Handle all states
+@if (userResource.isLoading()) {
+  <app-spinner />
+} @else if (userResource.error()) {
+  <app-error />
+} @else if (userResource.hasValue()) {
+  <app-user [user]="userResource.value()!" />
+}
+
+
+// BAD: Subscribing to service in component
+ngOnInit() {
+  this.userService.getById(this.userId()).subscribe(user => {
+    this.user = user;
+  });
+}
+
+// GOOD: Use resource for declarative data fetching
+protected readonly userResource = resource({
+  request: () => this.userId(),
+  loader: ({ request }) => this.userService.getById(request),
+});
+```