From 08b05f03089bb2145a0ece777ea6c567b4d91dfa Mon Sep 17 00:00:00 2001 From: James Daniels Date: Tue, 30 Jun 2026 17:21:55 -0400 Subject: [PATCH] Agents.md --- AGENTS.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..47f63050c --- /dev/null +++ b/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//` | 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//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` (`-canary.`). + - 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.