Imported from 1amageek/FirebaseAPI (
AGENTS.md). Install upstream withnpx skills add 1amageek/FirebaseAPI. Copyright stays with the author.
Repository Guidelines
Project Structure & Module Organization
FirebaseAPI is shipped as a Swift package. FirestoreAdminServer is the preferred server-side Admin product, FirestoreAPI is the compatibility all-in-one import, and FirestoreMongoCore is the explicit Mongo-compatible query-document product. Core model/query/snapshot values live in Sources/FirestoreCore, Admin workflow code lives in Sources/FirestoreAdmin, Codable helpers live in Sources/FirestoreCodable and Sources/FirestoreAdminCodable, authentication lives in Sources/FirestoreAuthCore and Sources/FirestoreAuth, and runtime configuration lives in Sources/FirestoreRuntimeConfig. Native Firestore request compilation belongs in Sources/FirestoreRPC, Pipeline request compilation belongs in Sources/FirestorePipelineRPC, generated protobuf messages belong in Sources/FirestoreProtobuf/Proto, generated gRPC stubs belong in Sources/FirestoreGRPCStubs/Proto, and concrete grpc-swift transport execution belongs in Sources/FirestoreGRPCTransport. Tests mirror these responsibilities under Tests/FirebaseAPITests, with emulator and live smoke tests kept opt-in by environment. The upstream protobuf definitions are vendored under the goolgeapis/ submodule; sync it before rebuilding generated code.
Build, Test, and Development Commands
swift build --configuration debugcompiles theFirestoreAPItarget and surfaces dependency issues early.perl -e 'alarm shift; exec @ARGV' 90 xcodebuild -scheme FirebaseAPI -destination 'platform=macOS' testruns the Swift Testing suite with a timeout.- Regenerate Firestore stubs after updating
goolgeapis:
./scripts/generate-firestore-protos.shCoding Style & Naming Conventions
Follow the Swift API Design Guidelines: 4-space indentation, UpperCamelCase for types, and lowerCamelCase for members. Favor struct or final class to match existing patterns, and keep public API documented with concise doc comments. Extensions should stay feature-scoped. Avoid editing generated files or mixing concrete networking logic outside Sources/FirestoreGRPCTransport; public API targets must not import protobuf, generated gRPC stubs, or grpc-swift transport modules.
Testing Guidelines
Tests are written with Swift Testing and live in Tests/FirebaseAPITests. Name new suites <Feature>Tests and individual methods test<Behavior> so they auto-discover. Run perl -e 'alarm shift; exec @ARGV' 90 xcodebuild -scheme FirebaseAPI -destination 'platform=macOS' test before submitting and add coverage for both Codable paths (Cadable/) and gRPC surfaces where possible. Integration checks that need Firebase credentials should load ServiceAccount.json outside source control; keep secrets in your keychain and pass paths via environment variables when running tests locally.
Commit & Pull Request Guidelines
Recent commits use short, imperative subjects (e.g., "Remove unused DocumentMask in gRPC requests"). Continue that format, keep the subject under 72 characters, and describe reasoning in the body when non-obvious. Pull requests should include: purpose summary, notes on regenerated protobufs, linked issues or tickets, verification steps (xcodebuild test output), and screenshots only when UI-affecting. Mark generated diffs clearly so reviewers can focus on hand-written changes.
Security & Configuration Tips
Do not commit credentials or generated proto outputs that include secrets. Store ServiceAccount.json outside the repo and reference it through environment variables like FIREBASE_SERVICE_ACCOUNT. When rotating credentials, update local keychains and re-run the regeneration command to ensure compiled clients stay in sync with current Firestore schemas.