### Set up PostgreSQL and Seed Database

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Install PostgreSQL, link it, start Docker, and then set up and seed the database for local development.

```sh
brew install postgresql@17
brew link postgresql@17 --force
docker-compose up -d
pnpm run setup
pnpm run --filter @argos/backend db:seed
```

--------------------------------

### Start Development Server

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Start the Argos development server after all dependencies and configurations are set up.

```sh
pnpm run dev
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Install all project dependencies using pnpm. Ensure pnpm is installed globally before running this command.

```sh
pnpm install
```

--------------------------------

### Generate SSL Certificates

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Generate local SSL certificates using mkcert for secure local development. Ensure mkcert is installed.

```sh
mkcert -install
mkcert "*.argos-ci.dev"
```

--------------------------------

### Install Playwright Dependencies

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Install Playwright and its dependencies, which are required for running End-to-End (E2E) tests.

```sh
npx playwright install --with-deps
```

--------------------------------

### Clone Argos Repository

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Clone the Argos repository to your local machine to begin development. Ensure you have Git installed.

```sh
git clone --depth 1 git@github.com:<your-username>/argos.git
cd argos
```

--------------------------------

### Set up Test Database

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Create and load data into the test database. This is a prerequisite for running tests.

```sh
NODE_ENV=test pnpm run --filter @argos/backend db:create
NODE_ENV=test pnpm run --filter @argos/backend db:load
```

--------------------------------

### Create Build

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/src/api/README.md

Initiates a new build by sending screenshot keys and commit information. The server responds with signed S3 URLs for uploading screenshots.

```APIDOC
## POST /builds

### Description
Creates a new build and provides signed S3 URLs for uploading screenshots. The client sends screenshot keys (SHA256) and commit information.

### Method
POST

### Endpoint
/builds

### Request Body
- **screenshotKeys** (array[string]) - Required - The SHA256 keys of the screenshots.
- **commit** (object) - Required - Information about the commit.
  - **sha** (string) - Required - The commit SHA.
  - **branch** (string) - Required - The branch name.
  - **message** (string) - Optional - The commit message.
  - **author** (string) - Optional - The author of the commit.
  - **date** (string) - Optional - The date of the commit.
- **parallel** (boolean) - Optional - Activates parallel mode for uploads.
- **parallelTotal** (integer) - Optional - The total number of upload batches when parallel mode is true.
- **parallelNonce** (integer) - Optional - The nonce of the current upload batch when parallel mode is true.

### Response
#### Success Response (200)
- **buildId** (string) - The ID of the created build.
- **screenshots** (array[object]) - A list of screenshots with upload URLs.
  - **key** (string) - The key of the screenshot.
  - **putUrl** (string) - The signed URL for uploading the screenshot (for legacy clients).
  - **postUrl** (string) - The signed URL for uploading the screenshot (for new clients).
  - **fields** (object) - Additional fields required for the upload (for new clients).
    - **key** (string) - The key for the upload.
    - **contentType** (string) - The content type of the upload.

### Request Example
```json
{
  "screenshotKeys": ["sha256_1", "sha256_2"],
  "commit": {
    "sha": "abcdef123456",
    "branch": "main",
    "message": "Initial commit",
    "author": "John Doe",
    "date": "2023-10-27T10:00:00Z"
  },
  "parallel": true,
  "parallelTotal": 4,
  "parallelNonce": 1
}
```

### Response Example
```json
{
  "buildId": "build_123",
  "screenshots": [
    {
      "key": "sha256_1",
      "putUrl": "https://s3.amazonaws.com/bucket/sha256_1?AWSAccessKeyId=...",
      "postUrl": "https://s3.amazonaws.com/bucket",
      "fields": {
        "key": "sha256_1",
        "contentType": "image/png"
      }
    }
  ]
}
```
```

--------------------------------

### Run Test Suite

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Execute the test suite to verify that your changes work as expected and haven't introduced regressions.

```sh
pnpm run test
```

--------------------------------

### Create Database Migration

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Generate a new migration file for database schema changes. Replace 'my_migration' with your migration name.

```sh
pnpm run --filter @argos/backend db:migrate:make my_migration
```

--------------------------------

### Run Unit Tests

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Execute unit tests that do not require external infrastructure like databases or Redis.

```bash
pnpm test:unit
```

--------------------------------

### Run Integration Tests

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Execute end-to-end (e2e) tests that require a running Postgres and Redis instance.

```bash
pnpm test:integration
```

--------------------------------

### Run Specific Test File

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Execute a single test file instead of the entire test suite. Replace 'path/to/test/file.e2e.test.ts' with the actual file path.

```sh
pnpm test path/to/test/file.e2e.test.ts
```

--------------------------------

### Push Branch and Create PR

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Push your local branch to your fork on GitHub and then create a pull request to submit your changes for review.

```sh
git push --set-upstream origin my-feature-branch
```

--------------------------------

### Truncate and Seed Database

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Truncate existing data and then populate the database with development data using the provided commands.

```sh
pnpm run --filter @argos/backend db:truncate && pnpm run --filter @argos/backend db:seed
```

--------------------------------

### Update/Finalize Build

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/src/api/README.md

Updates the build with screenshot information and marks the build as complete after verification.

```APIDOC
## PUT /builds/:buildId

### Description
Verifies the presence of screenshots and marks the build as complete. The client sends the screenshot keys and names.

### Method
PUT

### Endpoint
/builds/:buildId

### Parameters
#### Path Parameters
- **buildId** (string) - Required - The ID of the build to update.

### Request Body
- **screenshots** (array[object]) - Required - A list of screenshots with their keys and names.
  - **key** (string) - Required - The key of the screenshot.
  - **name** (string) - Required - The name of the screenshot.

### Request Example
```json
{
  "screenshots": [
    {
      "key": "sha256_1",
      "name": "screenshot_1.png"
    },
    {
      "key": "sha256_2",
      "name": "screenshot_2.png"
    }
  ]
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the build is complete.

### Response Example
```json
{
  "message": "Build finalized successfully."
}
```
```

--------------------------------

### Reset Test Database

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Reset the test database to a clean state. This command should be run in a test environment.

```sh
NODE_ENV=test pnpm run --filter @argos/backend db:reset
```

--------------------------------

### Dump Database Contents

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Create a dump of the current database contents. This can be useful for backups or sharing database state.

```sh
pnpm run --filter @argos/backend db:dump
```

--------------------------------

### Regenerate GraphQL Types

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Run this command from the repo root to regenerate backend and frontend GraphQL types after schema changes.

```bash
pnpm run codegen
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Execute all End-to-End (E2E) tests for the project. You can also run them in debug mode.

```sh
pnpm run test:e2e

# or in debug mode with
# pnpm run test:e2e --debug
```

--------------------------------

### Force Reinstall Dependencies

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

If you encounter a MODULE_NOT_FOUND error for '@argos-ci/mask-fingerprint', try forcing a reinstallation of dependencies.

```sh
pnpm i --force
```

--------------------------------

### Apply Latest Database Migration

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Apply all pending database migrations to bring the database schema up to the latest version.

```sh
pnpm run --filter @argos/backend db:migrate:latest
```

--------------------------------

### Update Hosts File

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Add these entries to your local hosts file to enable local development access to Argos domains.

```sh
# Argos
127.0.0.1 app.argos-ci.dev
127.0.0.1 api.argos-ci.dev
```

--------------------------------

### Lint Code Changes

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Run the linter to ensure your code adheres to the project's coding standards before committing.

```sh
pnpm run lint
```

--------------------------------

### Create Schema Migration

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Use this JavaScript code to define database schema changes for adding or modifying columns. It includes functions for both applying the change (up) and reverting it (down).

```javascript
export async function up(knex) {
  await knex.schema.alterTable("comments", (table) => {
    table.dateTime("editedAt").nullable();
  });
}
export async function down(knex) {
  await knex.schema.alterTable("comments", (table) => {
    table.dropColumn("editedAt");
  });
}
```

--------------------------------

### Reset Test Database

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Resets the test database schema to match the current SQL structure. This command should be run before executing e2e tests for the first time or after pulling new migrations. Ensure the environment variable NODE_ENV is set to 'test'.

```bash
NODE_ENV=test pnpm run --filter @argos/backend db:reset
```

--------------------------------

### Create a Feature Branch

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

Create a new branch for your feature or bug fix. It's recommended to pull the latest changes from the main branch before creating a new branch.

```sh
git checkout main
git pull origin main
git checkout -b my-feature-branch
```

--------------------------------

### Dispatch a Notification

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Call `sendNotification` with the notification type, data conforming to the schema, and an array of recipient user IDs. Opt-outs for configurable categories are handled automatically.

```typescript
await sendNotification({
  type: "review_submitted",
  data: {
    build_id: 1,
    build_url: "http://localhost:3000/builds/1",
    repository_name: "argos-ci/argos",
    user_name: "user",
  },
  recipients: ["user-id-1", "user-id-2"],
});
```

--------------------------------

### Terminate PostgreSQL Sessions

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Terminates active PostgreSQL sessions connected to the 'test' database. This is useful if the 'db:reset' command fails due to the database being in use. It connects to the 'postgres' database to find and terminate sessions for the 'test' database.

```bash
psql -h 127.0.0.1 -U postgres -d postgres -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'test' AND pid <> pg_backend_pid();"
```

--------------------------------

### Idempotent Insert with Ignore

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

This JavaScript snippet demonstrates how to perform an atomic insert into the 'comment_reactions' table. It uses `.onConflict().ignore()` to prevent duplicate entries based on 'commentId', 'userId', and 'emoji', and `.returning()` to check if the row was newly inserted.

```javascript
const inserted = await knex("comment_reactions")
  .insert({ commentId, userId, emoji })
  .onConflict(["commentId", "userId", "emoji"])
  .ignore()
  .returning("commentId");
if (inserted.length === 0) {
  return; // already existed, nothing to do
}
```

--------------------------------

### Register Notification Handler

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Import your new handler and add it to the `notificationHandlers` array in `src/notification/handlers/index.ts` to enable automatic type derivation and `sendNotification` prop typing.

```typescript
import { handler as reviewSubmittedHandler } from "./handlers/review_submitted";

const notificationHandlers = [
  reviewSubmittedHandler,
  // ...other handlers
];
```

--------------------------------

### Update Color Mode Class Name

Source: https://github.com/argos-ci/argos/blob/main/apps/frontend/index.html

Applies or removes the 'dark' class to the document's root element based on user preference or system settings. This function should be called on page load to set the initial theme.

```javascript
function updateColorModeClassName() { if ( localStorage.theme === "dark" || (!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches) ) { document.documentElement.classList.add("dark"); } else { document.documentElement.classList.remove("dark"); } } updateColorModeClassName();
```

--------------------------------

### Add GraphQL Resolver Mapping

Source: https://github.com/argos-ci/argos/blob/main/CONTRIBUTING.md

When adding a new type linked to a model in GraphQL, update the `codegen.ts` file with the corresponding mapper.

```typescript
const mappers = {
  Build: "@argos/backend/models#Build",
};
```

--------------------------------

### Define a Notification Handler

Source: https://github.com/argos-ci/argos/blob/main/apps/backend/AGENTS.md

Export a `handler` object from your notification file. This object includes the notification type, category, Zod schema for data validation, preview data, and the email rendering function.

```typescript
handler = defineNotificationHandler({
  type: "review_submitted",
  category: "review",
  schema: reviewSubmittedDataSchema,
  previewData: {
    build_id: 1,
    build_url: "http://localhost:3000/builds/1",
    repository_name: "argos-ci/argos",
    user_name: "user",
  },
  email: ReviewSubmittedEmail,
});
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.