screeps-deploy-action/GEMINI.md

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:

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.