Agents.md

Author: jamesdaniels

AGENTS.md

@@ -0,0 +1,95 @@
+# Repository Guide for AngularFire (`@angular/fire`)
+
+This document provides architectural context, build pipeline details, codebase navigation, and testing/release guidelines for AI agents and developers working in the AngularFire repository.
+
+---
+
+## 1. Architecture & Core Concepts
+
+AngularFire ([package.json](./package.json)) is the official Angular library for Firebase. It provides reactive, zone-aware bindings for Firebase JS SDK modules and RxFire.
+
+### Key Architectural Pillars
+
+1. **Modular Architecture & Secondary Entry Points**
+   - The library is structured into secondary package entry points (managed by `ng-packagr` via [src/ng-package.json](./src/ng-package.json)) corresponding to Firebase SDK modules (e.g., `auth`, `firestore`, `database`, `storage`, `functions`, `analytics`, `messaging`, `remote-config`, `performance`, `app-check`, `ai`, and `data-connect`).
+   - Each entry point exports zone-wrapped functions and observables from the modular Firebase JS SDK (`firebase/*`) and reactive RxFire helpers (`rxfire/*`).
+
+2. **Zone & Injection Context Management ([src/zones.ts](./src/zones.ts))**
+   - Firebase SDK async operations can trigger unwanted synchronous change detection or happen outside Angular's lifecycle.
+   - [ɵzoneWrap](./src/zones.ts#L124-L193) wraps Firebase and RxFire functions so that:
+     - Callback registration and execution run within or outside Angular zones appropriately using [ɵAngularFireSchedulers](./src/zones.ts#L70-L86) and [ɵZoneScheduler](./src/zones.ts#L38-L65).
+     - Execution verifies an Angular `EnvironmentInjector` context or logs dev-mode warnings when called outside injection context.
+     - Observables are piped to subscribe outside Angular zones and re-enter Angular zones on emission.
+
+3. **Core Dependency Injection ([src/core.ts](./src/core.ts))**
+   - Provides utilities like [ɵgetDefaultInstanceOf](./src/core.ts#L17-L29) and [ɵgetAllInstancesOf](./src/core.ts#L31-L43) to retrieve Firebase service instances (`FirebaseApp`, `Auth`, `Firestore`, etc.) from dependency injection containers or default Firebase instances.
+
+4. **Compatibility Layer ([src/compat](./src/compat))**
+   - Houses the legacy class-based AngularFire API (version 5/6 style AngularFire modules like `AngularFireAuthModule`, `AngularFirestoreModule`).
+
+---
+
+## 2. Where Code Lives
+
+| Path | Description |
+| :--- | :--- |
+| [src/core.ts](./src/core.ts) | Core Angular DI helpers, version metadata, and Firebase app container instance lookups. |
+| [src/zones.ts](./src/zones.ts) | Angular Zone management, scheduler implementations ([ɵZoneScheduler](./src/zones.ts#L38-L65)), and the core [ɵzoneWrap](./src/zones.ts#L124-L193) decorator function. |
+| `src/<module>/` | Individual modular Firebase service wrappers (e.g., `src/auth`, `src/firestore`, `src/storage`). Contains autogenerated `firebase.ts` and `rxfire.ts` exports along with Angular providers/modules. |
+| [src/compat/](./src/compat) | Legacy AngularFire compatibility modules and wrapper classes. |
+| [src/schematics/](./src/schematics) | Angular CLI Schematics for `ng add @angular/fire`, framework setup, migrations, and automated deployment builders (`ng deploy`). |
+| [tools/build.ts](./tools/build.ts) | Main build script that autogenerates zone wrappers, builds the library, and bundles schematics. |
+| [tools/jasmine.ts](./tools/jasmine.ts) | Entry point runner for Node/SSR unit tests using ServerTestingModule. |
+
+---
+
+## 3. Build Process
+
+The project is built using `npm run build`, which invokes [tools/build.ts](./tools/build.ts) (or [tools/build.sh](./tools/build.sh) in CI environments).
+
+### Build Pipeline Steps
+
+1. **Autogenerating Zone Wrappers ([zoneWrapExports](./tools/build.ts#L64-L257))**
+   - Prior to library compilation, [build.ts](./tools/build.ts) inspects exports of `firebase/*` and `rxfire/*` SDK packages using `ts-transformer-keys`.
+   - It autogenerates `firebase.ts` and `rxfire.ts` inside each service directory (`src/<module>/firebase.ts`).
+   - Functions are wrapped in [ɵzoneWrap](./src/zones.ts#L124-L193) with appropriate logging and blocking behavior.
+
+2. **Angular Library Compilation (`ng build`)**
+   - Uses `@angular-devkit/build-angular:ng-packagr` configured in [angular.json](./angular.json) to compile the source tree into `dist/packages-dist`.
+
+3. **Schematics Compilation ([compileSchematics](./tools/build.ts#L300-L340))**
+   - Uses `esbuild` to bundle schematics (`add`, `deploy`, `setup`, `update`) into CommonJS targets inside `dist/packages-dist/schematics`.
+   - Copies schematic metadata schemas (`collection.json`, `builders.json`, `versions.json`).
+
+4. **Version & Asset Sync ([replacePackageCoreVersion](./tools/build.ts#L264-L274))**
+   - Replaces `ANGULARFIRE2_VERSION` placeholders with the actual version from [package.json](./package.json) and synchronizes peer dependency versions in schematic JSONs.
+
+---
+
+## 4. Testing & Release Process
+
+### Testing
+
+Tests run against compiled outputs or directly in browsers using local Firebase Emulators (configured in `test/`).
+
+- **Unit Tests (Node / SSR)**:
+  - Run via `npm run test:node` or `npm run test:node-esm`.
+  - First compiles Jasmine test files (`npm run build:jasmine` using [tsconfig.jasmine.json](./tsconfig.jasmine.json)), then executes tests in Node using [tools/jasmine.ts](./tools/jasmine.ts).
+- **Browser & Emulator Tests**:
+  - Run via `npm run test:chrome-headless` (or `test:firefox-headless`).
+  - Uses the Firebase CLI to spin up local emulators: `firebase-tools emulators:exec --project=demo-123 "ng test --watch=false --browsers=ChromeHeadless"`.
+  - Uses Karma ([karma.conf.js](./karma.conf.js)) to run Jasmine specs inside the browser against emulated backends.
+
+### Release Pipeline
+
+Automated through GitHub Actions ([.github/workflows/test.yml](./.github/workflows/test.yml)):
+
+1. **Continuous Integration Matrix**:
+   - Every pull request or push to `main` executes `build`, followed by concurrent unit and browser test matrices across Node 20/22/24 and Ubuntu/macOS/Windows.
+2. **Tagging & Packaging ([tools/build.sh](./tools/build.sh))**:
+   - Resolves the npm tag based on Git branch/tag info:
+     - Commit builds on `main`: tagged as `canary` (`<version>-canary.<short-sha>`).
+     - Tag builds: tagged as `latest` or `next`.
+   - Generates an executable `publish.sh` script inside `./dist/packages-dist`.
+3. **Publishing**:
+   - When triggered by a publish release event or branch merge to `main`, `./dist/packages-dist/publish.sh` runs using the authenticated `NODE_AUTH_TOKEN` secret to release to npm.