[PATH-1503] - Added .agent.md file

.agent.md

@@ -0,0 +1,227 @@
+# Compass GitLab Integration Overview
+
+## General Development
+
+Before running any Node or Yarn based command, check and verify we're using the correct version of Node.js.
+
+We store the required Node.js version inside `.nvmrc` and we use nvm to manage our Node version.
+
+If there is a mismatch in Node version, you should run `nvm use` to resolve this. You may need to source nvm first.
+
+## Stack
+
+- **Language:** TypeScript (~4.5.5)
+- **Runtime:** Node.js 20.x (via Forge)
+- **Platform:** Atlassian Forge (serverless)
+- **UI Framework:** React 17 + Custom UI (separate workspace under `ui/`)
+- **Testing:** Jest 27 + ts-jest + jest-fetch-mock
+- **Linting:** ESLint 8 + TypeScript-ESLint + Prettier
+- **Package Manager:** Yarn
+- **Key Libraries:** `@forge/api`, `@forge/resolver`, `@forge/events`, `@atlassian/forge-graphql`, `js-yaml`, `exponential-backoff`
+
+---
+
+## Common Commands
+
+### Setup & Installation
+
+```shell
+# Use the correct Node version (check .nvmrc)
+nvm use
+
+# Install backend dependencies
+yarn
+
+# Install UI dependencies
+yarn ui:install
+
+# Build the UI (also syncs shared type files from backend to UI)
+yarn ui:build
+```
+
+### Development
+
+```shell
+# Start the UI dev server (watches for changes on port 3001)
+yarn ui:start
+
+# In a separate terminal, start the Forge tunnel
+forge tunnel
+```
+
+### Code Quality
+
+```shell
+# TypeScript type checking
+yarn compile
+
+# Run all linting (ESLint + Prettier check)
+yarn lint
+
+# Auto-fix linting and formatting issues
+yarn fix:prettier:and:lint
+
+# Run ESLint only
+yarn lint:eslint
+
+# Auto-fix ESLint issues only
+yarn lint:eslint:fix
+
+# Run Prettier check only
+yarn lint:prettier
+
+# Auto-fix Prettier formatting only
+yarn lint:prettier:fix
+
+# Deploy to development environment. Used to know whether the changes are valid for a forge environment or not
+forge deploy -f
+```
+
+### Testing
+
+```shell
+# Run all backend tests
+yarn test
+
+# Run UI tests
+yarn ui:test
+
+# Run a specific test file
+yarn test src/services/builds.test.ts
+
+# Run tests matching a specific name
+yarn test -t "name-of-spec"
+```
+
+---
+
+## Project Structure
+
+### Where to Find Files
+
+| What You're Looking For                   | Location             |
+| ----------------------------------------- | -------------------- |
+| **Main entry point (handler exports)**    | `src/index.ts`       |
+| **Forge app manifest**                    | `manifest.yml`       |
+| **App-wide constants**                    | `src/constants.ts`   |
+| **TypeScript type definitions**           | `src/types.ts`       |
+| **Feature flags**                         | `src/features.ts`    |
+| **GraphQL clients**                       | `src/client/`        |
+| **Forge resolver handlers**               | `src/resolvers/`     |
+| **Business logic services**               | `src/services/`      |
+| **Webtrigger & extension point handlers** | `src/entry/`         |
+| **Shared utilities**                      | `src/utils/`         |
+| **Data models & error types**             | `src/models/`        |
+| **React Custom UI frontend**              | `ui/src/`            |
+| **UI components**                         | `ui/src/components/` |
+| **UI hooks**                              | `ui/src/hooks/`      |
+| **UI services (invoke calls)**            | `ui/src/services/`   |
+| **Test fixtures & helpers**               | `src/__tests__/`     |
+
+### Key Architecture Notes
+
+- The backend (`src/`) and frontend (`ui/`) are separate Yarn workspaces.
+- Shared files (e.g. `features.ts`) live in the backend and are copied into the UI by `yarn ui:build`. Do not edit the copies in `ui/` directly.
+- The Forge manifest (`manifest.yml`) defines all extension points: component importer UI, admin page, config validator, data provider, webtrigger, queue consumers, and serverless functions.
+- All handler functions are exported from `src/index.ts` and referenced in `manifest.yml`.
+
+---
+
+## Forge App Development
+
+This project is a [Forge](https://developer.atlassian.com/platform/forge/) app — Atlassian's serverless platform for building Compass integrations. The following covers the full development lifecycle.
+
+### Prerequisites
+
+```shell
+# Install the Forge CLI globally (if not already installed)
+npm install -g @forge/cli
+
+# Log in to Forge (requires an Atlassian API token)
+forge login
+```
+
+### First-Time Setup
+
+```shell
+# Register the app (assigns a new app ID in manifest.yml — only do this for a new fork/clone). This changes the app id in the manifest.yml and should never be committed or pushed. The FORGE_APP_ID should remain untouched
+forge register
+
+# Set the required FORGE_APP_ID environment variable (use the UUID part after ari:cloud:ecosystem::app/)
+forge variables set FORGE_APP_ID <your-app-id>
+
+# Deploy the app to the development environment
+# Use -f / --no-verify to allow experimental/unpublished manifest modules
+forge deploy [-f]
+
+# Install the app on your Atlassian site
+# Select "Compass" as the product and enter your site (e.g. mysite.atlassian.net)
+# Use --upgrade if permissions/scopes have changed since last install
+forge install [--upgrade]
+```
+
+### Day-to-Day Development Workflow
+
+```shell
+# Terminal 1: Watch and serve the UI frontend
+yarn ui:start
+
+# Terminal 2: Run the Forge tunnel (proxies requests to your local code)
+forge tunnel
+```
+
+- `forge tunnel` connects your locally running code to the deployed app on your site, so you can see changes without re-deploying.
+- Refresh the Compass page in your browser to pick up changes.
+- If you see a `nullptr` exception while tunneling, add the following to the `app` section of `manifest.yml`:
+  ```yaml
+  app:
+    runtime:
+      snapshots: false
+  ```
+
+### Deploying Changes
+
+```shell
+# Deploy to the development environment (persists code changes)
+forge deploy [-f]
+
+# Deploy to staging or production
+forge deploy --environment staging [-f]
+forge deploy --environment production [-f]
+```
+
+Once an app is installed on a site, subsequent deploys are picked up automatically — no need to re-run `forge install`.
+
+### Environment Variables
+
+```shell
+# List all variables for the current environment
+forge variables list
+
+# Set a variable (plaintext)
+forge variables set KEY value
+
+# Set an encrypted/secret variable
+forge variables set KEY value --encrypt
+
+# Remove a variable
+forge variables unset KEY
+```
+
+The app uses these variables:
+
+- `FORGE_APP_ID` — Required. The UUID portion of the app's ARI from `manifest.yml`.
+- `APP_ENV` — Set to `development` to enable `console.log` output via the `debugLog` utility (`src/utils/debugLog.ts`).
+
+### Viewing Logs
+
+```shell
+# View logs from deployed functions
+forge logs
+```
+
+Logs from `console.log` calls are only visible locally when using `debugLog` with `APP_ENV=development`. In all other environments, use `forge logs`.
+
+### Permissions & Scopes
+
+The app's required permissions are declared in `manifest.yml` under `permissions`. If you add new scopes, re-deploy and re-install with `forge install --upgrade` to apply them.