@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/presets/angular-express/skills/angular-developer/references/components.md

@@ -0,0 +1,117 @@
+# Components
+
+Angular components are the fundamental building blocks of an application. Each component consists of a TypeScript class with behaviors, an HTML template, and a CSS selector.
+
+## Component Definition
+
+Use the `@Component` decorator to define a component's metadata.
+
+```ts
+@Component({
+  selector: 'app-profile',
+  template: `
+    <img src="profile.jpg" alt="Profile photo" />
+    <button (click)="save()">Save</button>
+  `,
+  styles: `
+    img {
+      border-radius: 50%;
+    }
+  `,
+})
+export class Profile {
+  save() {
+    /* ... */
+  }
+}
+```
+
+## Metadata Options
+
+- `selector`: The CSS selector that identifies this component in templates.
+- `template`: Inline HTML template (preferred for small templates).
+- `templateUrl`: Path to an external HTML file.
+- `styles`: Inline CSS styles.
+- `styleUrl` / `styleUrls`: Path(s) to external CSS file(s).
+- `imports`: Lists the components, directives, or pipes used in this component's template.
+
+## Using Components
+
+To use a component, add it to the `imports` array of the consuming component and use its selector in the template.
+
+```ts
+@Component({
+  selector: 'app-root',
+  imports: [Profile],
+  template: `<app-profile />`,
+})
+export class App {}
+```
+
+## Template Control Flow
+
+Angular uses built-in blocks for conditional rendering and loops.
+
+### Conditional Rendering (`@if`)
+
+Use `@if` to conditionally show content. You can include `@else if` and `@else` blocks.
+
+```html
+@if (user.isAdmin) {
+<admin-dashboard />
+} @else if (user.isModerator) {
+<mod-dashboard />
+} @else {
+<standard-dashboard />
+}
+```
+
+**Result aliasing**: Save the result of the expression for reuse.
+
+```html
+@if (user.settings(); as settings) {
+<p>Theme: {{ settings.theme }}</p>
+}
+```
+
+### Loops (`@for`)
+
+The `@for` block iterates over collections. The `track` expression is **required** for performance and DOM reuse.
+
+```html
+<ul>
+  @for (item of items(); track item.id; let i = $index, total = $count) {
+  <li>{{ i + 1 }}/{{ total }}: {{ item.name }}</li>
+  } @empty {
+  <li>No items to display.</li>
+  }
+</ul>
+```
+
+**Implicit Variables**: `$index`, `$count`, `$first`, `$last`, `$even`, `$odd`.
+
+### Switching Content (`@switch`)
+
+The `@switch` block renders content based on a value. It uses strict equality (`===`) and has **no fallthrough**.
+
+```html
+@switch (status()) { @case ('loading') { <app-spinner /> } @case ('error') { <app-error-msg /> }
+@case ('success') { <app-data-grid /> } @default {
+<p>Unknown status</p>
+} }
+```
+
+**Exhaustive Type Checking**: Use `@default never;` to ensure all cases of a union type are handled.
+
+```html
+@switch (state) { @case ('on') { ... } @case ('off') { ... } @default never; // Errors if a new
+state like 'standby' is added }
+```
+
+## Core Concepts
+
+- **Host Element**: The DOM element that matches the component's selector.
+- **View**: The DOM rendered by the component's template inside the host element.
+- **Standalone**: By default, components are standalone (since Angular 19, `standalone: true` is default). For older versions, `standalone: true` must be explicit or the component must be part of an `NgModule`.
+- **Component Tree**: Angular applications are structured as a tree of components, where each component can host child components.
+- **Component Naming**: Do not add suffixes the `Component` suffix for Component classes (e.g., AppComponent) unless the project has been configured to use that naming configuration.

package/presets/angular-express/skills/angular-developer/references/creating-services.md

@@ -0,0 +1,97 @@
+# Creating and Using Services
+
+Services in Angular are reusable pieces of code that handle data fetching, business logic, or state management that multiple components or other services need to access.
+
+## Creating a Service
+
+You can generate a service using the Angular CLI:
+
+```bash
+ng generate service my-data
+```
+
+Or you can manually create a TypeScript class and decorate it with `@Service()`.
+
+```ts
+import {Service} from '@angular/core';
+
+@Service()
+export class BasicDataStore {
+  private data: string[] = [];
+
+  addData(item: string): void {
+    this.data.push(item);
+  }
+
+  getData(): string[] {
+    return [...this.data];
+  }
+}
+```
+
+### The `@Service` decorator
+
+Using `@Service` is the recommended approach for most services. It tells Angular to:
+
+- **Create a single instance (singleton)** for the entire application.
+- **Make it available everywhere** automatically, without needing to list it in any `providers` array.
+- **Enable tree-shaking**, meaning the service is only included in the final JavaScript bundle if it is actually injected somewhere.
+
+#### The `autoProvided` option
+
+If you don't want to create a singleton of your service, you can set `@Service({autoProvided: false})` and declare the service a `providers` array.
+
+## Injecting a Service
+
+Once a service is created, you can inject it into components, directives, or other services using the `inject()` function.
+
+### Injecting into a Component
+
+```ts
+import {Component, inject} from '@angular/core';
+import {BasicDataStore} from './basic-data-store.service';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <div>
+      <p>Data items: {{ dataStore.getData().length }}</p>
+      <button (click)="dataStore.addData('New Item')">Add Item</button>
+    </div>
+  `,
+})
+export class Example {
+  // Inject the service as a class field
+  dataStore = inject(BasicDataStore);
+}
+```
+
+### Injecting into Another Service
+
+Services can inject other services in the exact same way.
+
+```ts
+import {Injectable, inject} from '@angular/core';
+import {AdvancedDataStore} from './advanced-data-store.service';
+
+@Service()
+export class BasicDataStore {
+  // Injecting another service
+  private advancedDataStore = inject(AdvancedDataStore);
+
+  private data: string[] = [];
+
+  getData(): string[] {
+    // Combine data from this service and the injected service
+    return [...this.data, ...this.advancedDataStore.getData()];
+  }
+}
+```
+
+## Advanced Service Patterns
+
+While `@Service` covers most scenarios, you may sometimes need:
+
+- **Component-specific instances**: If a component needs its own isolated instance of a service, provide it directly in the component's `@Component({ providers: [MyService] })` array and set the `autoProvided: false` option: `@Service({autoProvided: false})`
+- **Factory providers**: For dynamic creation.
+- **Value providers**: For injecting configuration objects.

package/presets/angular-express/skills/angular-developer/references/data-resolvers.md

@@ -0,0 +1,69 @@
+# Data Resolvers
+
+Data resolvers fetch data before a route activates, ensuring components have the necessary data upon rendering.
+
+## Creating a Resolver
+
+Implement the `ResolveFn` type.
+
+```ts
+export const userResolver: ResolveFn<User> = (route, state) => {
+  const userService = inject(UserService);
+  const id = route.paramMap.get('id')!;
+  return userService.getUser(id);
+};
+```
+
+## Configuring the Route
+
+Add the resolver under the `resolve` key.
+
+```ts
+{
+  path: 'user/:id',
+  component: UserProfile,
+  resolve: {
+    user: userResolver
+  }
+}
+```
+
+## Accessing Resolved Data
+
+### 1. Via `ActivatedRoute` (Traditional)
+
+```ts
+private route = inject(ActivatedRoute);
+data = toSignal(this.route.data);
+user = computed(() => this.data().user);
+```
+
+### 2. Via Component Inputs (Modern)
+
+Enable `withComponentInputBinding()` in `provideRouter` to pass resolved data directly to `@Input` or `input()`.
+
+```ts
+// app.config.ts
+provideRouter(routes, withComponentInputBinding());
+
+// component.ts
+user = input.required<User>();
+```
+
+## Error Handling
+
+Navigation is blocked if a resolver fails.
+
+- Use `withNavigationErrorHandler` for global handling.
+- Use `catchError` within the resolver to return a `RedirectCommand` or fallback data.
+
+```ts
+return userService
+  .get(id)
+  .pipe(catchError(() => of(new RedirectCommand(router.parseUrl('/error')))));
+```
+
+## Best Practices
+
+- **Keep it lightweight**: Fetch only critical data.
+- **Provide feedback**: Listen to router events to show a global loading bar during navigation, as the UI stays on the old page until the resolver finishes.

package/presets/angular-express/skills/angular-developer/references/define-routes.md

@@ -0,0 +1,67 @@
+# Define Routes
+
+Routes are objects that define which component should render for a specific URL path.
+
+## Basic Configuration
+
+Define routes in a `Routes` array and provide them using `provideRouter` in your `appConfig`.
+
+```ts
+// app.routes.ts
+export const routes: Routes = [
+  {path: '', component: HomePage},
+  {path: 'admin', component: AdminPage},
+];
+
+// app.config.ts
+export const appConfig: ApplicationConfig = {
+  providers: [provideRouter(routes)],
+};
+```
+
+## URL Paths
+
+- **Static**: Matches an exact string (e.g., `'admin'`).
+- **Route Parameters**: Dynamic segments prefixed with a colon (e.g., `'user/:id'`).
+- **Wildcard**: Matches any URL using `**`. Useful for "Not Found" pages. **Always place at the end of the array.**
+
+## Matching Strategy
+
+Angular uses a **first-match wins** strategy. Specific routes must come before less specific ones.
+
+## Redirects
+
+Use `redirectTo` to point one path to another.
+
+```ts
+{ path: 'articles', redirectTo: '/blog' },
+{ path: 'blog', component: Blog },
+```
+
+## Page Titles
+
+Associate titles with routes for accessibility. Titles can be static or dynamic (via `ResolveFn` or a custom `TitleStrategy`).
+
+```ts
+{ path: 'home', component: Home, title: 'Home Page' }
+```
+
+## Route Data and Providers
+
+- **Static Data**: Attach metadata using the `data` property.
+- **Route Providers**: Scope dependencies to a specific route and its children using the `providers` array.
+
+## Nested (Child) Routes
+
+Define sub-views using the `children` property. Parent components must include a `<router-outlet />`.
+
+```ts
+{
+  path: 'product/:id',
+  component: Product,
+  children: [
+    { path: 'info', component: ProductInfo },
+    { path: 'reviews', component: ProductReviews },
+  ],
+}
+```

package/presets/angular-express/skills/angular-developer/references/defining-providers.md

@@ -0,0 +1,72 @@
+# Defining Dependency Providers
+
+Angular offers automatic and manual ways to provide dependencies to its Dependency Injection (DI) system.
+
+## Automatic Provision
+
+The most common way to provide a service is using `providedIn: 'root'` on an `@Injectable()`.
+
+### InjectionToken
+
+Use `InjectionToken` for non-class dependencies (configuration objects, functions, primitives). An `InjectionToken` can also be automatically provided.
+
+```ts
+import {InjectionToken} from '@angular/core';
+
+export interface AppConfig {
+  apiUrl: string;
+}
+
+export const APP_CONFIG = new InjectionToken<AppConfig>('app.config', {
+  providedIn: 'root',
+  factory: () => ({apiUrl: 'https://api.example.com'}),
+});
+```
+
+## Manual Provision
+
+You use the `providers` array when a service lacks `providedIn`, when you want a new instance for a specific component, or when configuring runtime values.
+
+```ts
+@Component({
+  providers: [
+    // Shorthand for { provide: LocalService, useClass: LocalService }
+    LocalService,
+
+    // useClass: Swap implementations
+    {provide: Logger, useClass: BetterLogger},
+
+    // useValue: Provide static values
+    {provide: API_URL_TOKEN, useValue: 'https://api.example.com'},
+
+    // useFactory: Generate value dynamically
+    {
+      provide: ApiClient,
+      useFactory: (http = inject(HttpClient)) => new ApiClient(http),
+    },
+
+    // useExisting: Create an alias
+    {provide: OldLogger, useExisting: NewLogger},
+
+    // multi: Provide multiple values for the same token as an array
+    {provide: INTERCEPTOR_TOKEN, useClass: AuthInterceptor, multi: true},
+  ],
+})
+export class Example {}
+```
+
+## Scopes of Providers
+
+- **Application Bootstrap**: Global singletons. Use for HTTP clients, logging, or app-wide config.
+- **Component/Directive**: Isolated instances. Use for component-specific state or forms. Services are destroyed when the component is destroyed.
+- **Route**: Feature-specific services loaded only with specific routes.
+
+## Library Pattern: `provide*` functions
+
+Library authors should export functions that return provider arrays to encapsulate configuration:
+
+```ts
+export function provideAnalytics(config: AnalyticsConfig): Provider[] {
+  return [{provide: ANALYTICS_CONFIG, useValue: config}, AnalyticsService];
+}
+```

package/presets/angular-express/skills/angular-developer/references/di-fundamentals.md

@@ -0,0 +1,120 @@
+# Dependency Injection (DI) Fundamentals
+
+Dependency Injection (DI) is a design pattern used to organize and share code across an application by allowing you to "inject" features into different parts. This improves code maintainability, scalability, and testability.
+
+## How DI Works in Angular
+
+There are two primary ways code interacts with Angular's DI system:
+
+1.  **Providing**: Making values (objects, functions, primitives) available to the DI system.
+2.  **Injecting**: Asking the DI system for those values.
+
+Angular components, directives, and services automatically participate in DI.
+
+## Services
+
+A **service** is the most common way to share data and functionality across an application. It is a TypeScript class decorated with `@Injectable()`.
+
+### Creating a Service
+
+Use the `providedIn: 'root'` option in the `@Injectable` decorator to make the service a singleton available throughout the entire application. This is the recommended approach for most services.
+
+```ts
+import {Injectable} from '@angular/core';
+
+@Injectable({
+  providedIn: 'root', // Makes this a singleton available everywhere
+})
+export class AnalyticsLogger {
+  trackEvent(category: string, value: string) {
+    console.log('Analytics event logged:', {category, value});
+  }
+}
+```
+
+Common uses for services include:
+
+- Data clients (API calls)
+- State management
+- Authentication and authorization
+- Logging and error handling
+- Utility functions
+
+## Injecting Dependencies
+
+Use Angular's `inject()` function to request dependencies.
+
+### The `inject()` Function
+
+You can use the `inject()` function to get an instance of a service (or any other provided token).
+
+```ts
+import {Component, inject} from '@angular/core';
+import {Router} from '@angular/router';
+import {AnalyticsLogger} from './analytics-logger.service';
+
+@Component({
+  selector: 'app-navbar',
+  template: `<a href="#" (click)="navigateToDetail($event)">Detail Page</a>`,
+})
+export class Navbar {
+  // Injecting dependencies using class field initializers
+  private router = inject(Router);
+  private analytics = inject(AnalyticsLogger);
+
+  navigateToDetail(event: Event) {
+    event.preventDefault();
+    this.analytics.trackEvent('navigation', '/details');
+    this.router.navigate(['/details']);
+  }
+}
+```
+
+### Where can `inject()` be used? (Injection Context)
+
+You can call `inject()` in an **injection context**. The most common injection contexts are during the construction of a component, directive, or service.
+
+Valid places to call `inject()`:
+
+1.  **Class field initializers** (Recommended)
+2.  **Constructor body**
+3.  **Route guards and resolvers** (which are executed in an injection context)
+4.  **Factory functions** used in providers
+
+```typescript
+import {Component, Directive, Injectable, inject, ElementRef} from '@angular/core';
+import {HttpClient} from '@angular/common/http';
+
+// 1. In a Component (Field Initializer & Constructor)
+@Component({
+  /*...*/
+})
+export class Example {
+  private service1 = inject(MyService); // ✅ Field initializer
+
+  private service2: MyService;
+  constructor() {
+    this.service2 = inject(MyService); // ✅ Constructor body
+  }
+}
+
+// 2. In a Directive
+@Directive({
+  /*...*/
+})
+export class MyDirective {
+  private element = inject(ElementRef); // ✅ Field initializer
+}
+
+// 3. In a Service
+@Injectable({providedIn: 'root'})
+export class MyService {
+  private http = inject(HttpClient); // ✅ Field initializer
+}
+
+// 4. In a Route Guard (Functional)
+export const authGuard = () => {
+  const auth = inject(AuthService); // ✅ Route Guard
+  return auth.isAuthenticated();
+};
+```

package/presets/angular-express/skills/angular-developer/references/e2e-testing.md

@@ -0,0 +1,66 @@
+# End-to-End (E2E) Testing
+
+This project uses [Cypress](https://www.cypress.io/) for end-to-end (E2E) testing, which simulates real user interactions in a browser. The E2E tests are located primarily within the `devtools/` package.
+
+## Running E2E Tests
+
+The primary way to run E2E tests is through the `pnpm` script defined in the root `package.json`.
+
+1.  **Build DevTools:** The E2E tests run against a built version of the devtools extension. You must build it first:
+
+    ```shell
+    pnpm -F ng-devtools-mcp build:dev
+    ```
+
+2.  **Run Cypress:** Use the `cy:open` or `cy:run` script:
+    - To open the interactive Cypress Test Runner:
+      ```shell
+      pnpm -F ng-devtools-mcp cy:open
+      ```
+    - To run the tests headlessly in the terminal (ideal for CI):
+      ```shell
+      pnpm -F ng-devtools-mcp cy:run
+      ```
+
+## Test Structure
+
+- **Configuration:** The main Cypress configuration is located at `devtools/cypress.json`.
+- **Specs:** Test files (specs) are located in `devtools/cypress/integration/`.
+- **Custom Commands:** Reusable custom commands and actions are defined in `devtools/cypress/support/`.
+
+### Example E2E Test Snippet
+
+A typical test might look like this:
+
+```typescript
+// in devtools/cypress/integration/profiler.spec.ts
+
+describe('Profiler', () => {
+  beforeEach(() => {
+    cy.visit('/?e2e-app');
+    cy.wait(1000);
+    cy.get('ng-devtools-tabs').find('a').contains('Profiler').click();
+  });
+
+  it('should record and display profiling data', () => {
+    // Find the record button and click it
+    cy.get('button[aria-label="start-recording-button"]').click();
+
+    // Interact with the test application to generate profiling data
+    cy.get('body').find('#cards button').first().click();
+    cy.wait(500);
+
+    // Stop recording
+    cy.get('button[aria-label="stop-recording-button"]').click();
+
+    // Assert that the flame graph is now visible
+    cy.get('ng-devtools-recording-timeline').find('canvas').should('be.visible');
+  });
+});
+```
+
+### Best Practices
+
+- **Use `data-` attributes:** Whenever possible, use `data-cy` or similar attributes for selecting elements to make tests more resilient to CSS or structural changes.
+- **Custom Commands:** Encapsulate common sequences of actions into custom commands in the `support` directory to keep tests clean and readable.
+- **Wait for Application State:** Use `cy.wait()` for arbitrary waits sparingly. Prefer to wait for specific UI elements to appear or for network requests to complete to avoid flaky tests.

package/presets/angular-express/skills/angular-developer/references/effects.md

@@ -0,0 +1,83 @@
+# Side Effects with `effect` and `afterRenderEffect`
+
+In Angular, an **effect** is an operation that runs whenever one or more signal values it tracks change.
+
+## When to use `effect`
+
+Effects are intended for syncing signal state to imperative, non-signal APIs.
+
+**Valid Use Cases:**
+
+- Logging analytics.
+- Syncing state to `localStorage` or `sessionStorage`.
+- Performing custom rendering to a `<canvas>` or 3rd-party charting library.
+
+**CRITICAL RULE: DO NOT use effects to propagate state.**
+If you find yourself using `.set()` or `.update()` on a signal _inside_ an effect to keep two signals in sync, you are making a mistake. This causes `ExpressionChangedAfterItHasBeenChecked` errors and infinite loops. **Always use `computed()` or `linkedSignal()` for state derivation.**
+
+## Basic Usage
+
+Effects execute asynchronously during the change detection process. They always run at least once.
+
+```ts
+import { Component, signal, effect } from '@angular/core';
+
+@Component({...})
+export class Example {
+  count = signal(0);
+
+  constructor() {
+    // Effect must be created in an injection context (e.g., a constructor)
+    effect((onCleanup) => {
+      console.log(`Count changed to ${this.count()}`);
+
+      const timer = setTimeout(() => console.log('Timer finished'), 1000);
+
+      // Cleanup function runs before the next execution, or when destroyed
+      onCleanup(() => clearTimeout(timer));
+    });
+  }
+}
+```
+
+## DOM Manipulation with `afterRenderEffect`
+
+Standard `effect` runs _before_ Angular updates the DOM. If you need to manually inspect or modify the DOM based on a signal change (e.g., integrating a 3rd party UI library), use `afterRenderEffect`.
+
+`afterRenderEffect` runs after Angular has finished rendering the DOM.
+
+### Render Phases
+
+To prevent reflows (forced layout thrashing), `afterRenderEffect` forces you to divide your DOM reads and writes into specific phases.
+
+```ts
+import { Component, afterRenderEffect, viewChild, ElementRef } from '@angular/core';
+
+@Component({...})
+export class Chart {
+  canvas = viewChild.required<ElementRef>('canvas');
+
+  constructor() {
+    afterRenderEffect({
+      // 1. Read from the DOM
+      earlyRead: () => {
+        return this.canvas().nativeElement.getBoundingClientRect().width;
+      },
+      // 2. Write to the DOM (receives the result of the previous phase)
+      write: (width) => {
+        // NEVER read from the DOM in the write phase.
+        setupChart(this.canvas().nativeElement, width);
+      }
+    });
+  }
+}
+```
+
+**Available Phases (executed in this order):**
+
+1. `earlyRead`
+2. `write` (Never read here)
+3. `mixedReadWrite` (Avoid if possible)
+4. `read` (Never write here)
+
+_Note: `afterRenderEffect` only runs on the client, never during Server-Side Rendering (SSR)._