# Gemini Code Assistant Guide: `screeps-deploy-action`

This document provides a guide for Large Language Models (LLMs) and developers on understanding and interacting with the `screeps-deploy-action` project.

## Project Overview

`screeps-deploy-action` is a GitHub Action designed to automate the deployment of JavaScript code to the online programming game Screeps. This project is aimed at supporting both GitHub and Gitea workflows, allowing developers to push their code from a Git repository directly to either the official `screeps.com` server or a private server. It utilizes **Gitea Workflows** (located in `.gitea/workflows`), which are largely compatible with GitHub Actions with minor syntax changes, for its continuous integration and deployment needs.

The action's core logic is in `index.js`. It uses the `screeps-api` library to communicate with the Screeps server. The action is configured via a workflow file (e.g., `.github/workflows/main.yml`) using inputs defined in `action.yaml`.

### Key Files

-   **`action.yaml`**: The manifest file for the GitHub Action. It defines the inputs, outputs, and execution environment for the action.
-   **`index.js`**: The main entry point for the action. It contains the core logic for reading files, connecting to the Screeps API, and uploading the code.
-   **`package.json`**: Defines the project's metadata and dependencies. The key dependency is `screeps-api`.
-   **`README.md`**: Provides user-facing documentation, including setup and usage examples.

## Core Functionality

The action performs the following steps:

1.  **Reads Inputs**: It reads the configuration provided by the user in their workflow file. This includes server connection details, authentication credentials, and file paths.
2.  **Authentication**: It authenticates with the Screeps server using either a token or a username/password.
3.  **File Processing**:
    *   It reads all `.js` files from the repository matching the provided `pattern`.
    *   It can optionally perform placeholder replacements (e.g., `{{gitHash}}`, `{{deployTime}}`) in a specified file (`replace_file`) before deployment.
4.  **Code Deployment**: It uploads the processed files to the specified `branch` on the Screeps server.

## Usage

To use this action, a developer would create a `.yml` file in their `.github/workflows` directory.

**Example Workflow:**

```yaml
name: Deploy to Screeps
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to screeps.com
        uses: ./
        with:
          token: ${{ secrets.SCREEPS_TOKEN }}
          branch: 'default'
          pattern: '*.js'
```

### Configuration Inputs

The action is configured using the `with` key in the workflow step. The available inputs are defined in `action.yaml`:

-   **`token`**: (Required) The authentication token for the Screeps API. It is recommended to store this as a secret.
-   **`protocol`**: The server protocol (`http` or `https`). Defaults to `https`.
-   **`hostname`**: The server hostname. Defaults to `screeps.com`.
-   **`port`**: The server port. Defaults to `443`.
-   **`path`**: The server path. Defaults to `/`.
-   **`username`**: The Screeps username (used if `token` is not provided).
-   **`password`**: The Screeps password (used if `token` is not provided).
-   **`branch`**: The in-game branch to deploy the code to. Defaults to `default`.
-   **`pattern`**: A glob pattern for the files to deploy. Defaults to `*.js`.
-   **`replace_file`**: Path to a file where placeholders like `{{gitHash}}` and `{{deployTime}}` should be replaced.
-   **`source_map_path`**: Path to a `main.js.map` file for Source Map support.

## Modifying the Code

When asked to modify the action's behavior, the primary file to edit will almost always be `index.js`.

-   For changes to the action's inputs or outputs, `action.yaml` must also be updated.
-   The core deployment logic is within the `postCode` function in `index.js`.
-   File reading is handled by `readFilesIntoDict`.
-   Placeholder replacement is handled by `readReplaceAndWriteFiles`.

Before making changes, always review the existing code and the `screeps-api` documentation to understand how it interacts with the Screeps server. After making changes, ensure that any associated tests are updated or added.
