Added the ability to replace some placeholders in the screeps code (#12)

added the `git-replace` option.
Replaceing {{gitRef}}, {{deployTime}} and {{gitHash}}.

Reviewed-on: #12
Co-authored-by: Philipp Horstenkamp <philipp@horstenkamp.de>
Co-committed-by: Philipp Horstenkamp <philipp@horstenkamp.de>

README.md

@@ -1,3 +1,65 @@
 # screeps-deploy-action
 
-This action deploys screeps code via github / gitea actions.
+## Introduction
+
+This GitHub Action facilitates the uploading of code to a Screeps server.
+It's designed to automate the process of deploying JavaScript code to your Screeps account, ensuring that your game logic is consistently and efficiently updated.
+Prerequisites
+
+    A Screeps account with an access token.
+    A GitHub or Gitea repository with your Screeps code.
+
+## Usage
+
+To use this action, you need to set it up in your workflow .yml file located in the .github/workflows directory of your repository.
+
+## Inputs
+
+- `protocol`: The protocol to use (default: https).
+- `hostname`: The hostname of the Screeps server (default: screeps.com).
+- `port`: The port to use (default: 443).
+- `path`: The path for the API (default: /).
+- `token`: Authentication token for Screeps.
+- `username`: Username for Screeps account (used if no token is provided).
+- `password`: Password for Screeps account (used if no token is provided).
+- `prefix`: Directory prefix for file paths.
+- `pattern`: Glob pattern to match files (default: *.js).
+- `branch`: Branch in Screeps to which the code will be uploaded (default: default).
+- `git-replace`: Overwrite "{{gitRef}}", "{{gitHash}}" and "{{deployTime}}" values in files matching the pattern.
+
+Example Workflow
+
+Create a `.yml` file (e.g., `screeps-deploy.yml`) in your repository's `.github/workflows` directory or `.gitea/workflows` directory:
+
+```yaml
+name: Deploy to Screeps
+
+on: [push]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Upload to Screeps
+      uses: Screeps/screeps-deploy-action@main
+      with:
+        token: ${{ secrets.SCREEPS_TOKEN }}
+        pattern: '**/*.js'
+        branch: 'default'
+        git-replace: /some_options.js
+```
+
+In this example:
+
+- The action runs on every push to the repository.
+- It checks out your code.
+- Then, it uses the "Upload to Screeps" action to deploy the code to your Screeps account.
+- You need to set SCREEPS_TOKEN in your repository secrets.
+
+## Advanced Usage
+
+Please note that you can easily filter your deployment branches in the push action.
+Multiple deploy steps or jobs are recomended for mulitple deployments.

action.yaml

@@ -37,6 +37,9 @@ inputs:
     description: 'Branch in Screeps to which the code will be uploaded (default: default).'
     required: false
     default: default
+  git-replace:
+    description: Allows for the overwrite of the "{{gitRef}}", "{{gitHash}}" and "{{deployTime}}" values in the file matching the file pattern. The file pattern will be combined with the prefix.
+    required: false
 runs:
   using: node12
   main: index.js

index.js

@@ -4,6 +4,69 @@ const fs = require("fs");
 const glob = require("glob");
 const path = require("path");
 
+/**
+ * Replaces specific placeholder strings within the provided content with corresponding dynamic values.
+ *
+ * This function specifically targets three placeholders:
+ * - {{gitHash}} is replaced with the current Git commit hash, obtained from the GITHUB_SHA environment variable.
+ * - {{gitRef}} is replaced with the Git reference (branch or tag) that triggered the workflow, obtained from the GITHUB_REF environment variable.
+ * - {{deployTime}} is replaced with the current ISO timestamp.
+ *
+ * Note: This function is designed for use within a GitHub Actions workflow where GITHUB_SHA and GITHUB_REF environment variables are automatically set.
+ *
+ * @param {string} content - The string content in which placeholders are to be replaced.
+ * @returns {string} The content with placeholders replaced by their respective dynamic values.
+ */
+function replacePlaceholders(content) {
+  const deployTime = new Date().toISOString();
+  return content
+    .replace(/{{gitHash}}/g, process.env.GITHUB_SHA)
+    .replace(/{{gitRef}}/g, process.env.GITHUB_REF)
+    .replace(/{{deployTime}}/g, deployTime);
+}
+
+/**
+ * Reads all files matching a specified pattern, replaces certain placeholders in their content, and writes the updated content back to the files.
+ *
+ * This function searches for files in the filesystem using the provided glob pattern, optionally prefixed. It reads each file,
+ * uses the `replacePlaceholders` function to replace specific placeholders in the file's content, and then writes the modified content
+ * back to the original file. This is useful for dynamically updating file contents in a batch process, such as during a build or deployment.
+ *
+ * @param {string} pattern - The glob pattern used to find files. Example: '*.js' for all JavaScript files.
+ * @param {string} [prefix] - An optional directory prefix to prepend to the glob pattern. This allows searching within a specific directory.
+ * @returns {Promise<string[]>} A promise that resolves with an array of file paths that were processed, or rejects with an error if the process fails.
+ */
+async function readReplaceAndWriteFiles(pattern, prefix) {
+  return new Promise((resolve, reject) => {
+    const globPattern = prefix ? path.join(prefix, pattern) : pattern;
+
+    glob(globPattern, async (err, files) => {
+      if (err) {
+        return reject(err);
+      }
+      let processPromises = [];
+
+      files.forEach((file) => {
+        let processPromise = fs.promises
+          .readFile(file, "utf8")
+          .then((content) => {
+            content = replacePlaceholders(content);
+            return fs.promises.writeFile(file, content);
+          });
+
+        processPromises.push(processPromise);
+      });
+
+      try {
+        await Promise.all(processPromises);
+        resolve(files);
+      } catch (processError) {
+        reject(processError);
+      }
+    });
+  });
+}
+
 /**
  * Reads files matching a glob pattern into a dictionary.
  * @param {string} pattern - Glob pattern to match files.
@@ -88,6 +151,12 @@ async function postCode() {
   const pattern = core.getInput("pattern") || "*.js";
   const branch = core.getInput("branch") || "default";
 
+  const gitReplace = core.getInput("git-replace") || null;
+
+  if (gitReplace) {
+    await readReplaceAndWriteFiles(gitReplace, prefix);
+  }
+
   const files_to_push = await readFilesIntoDict(pattern, prefix);
 
   core.info(`Trying to upload the following files to ${branch}:`);
@@ -134,5 +203,4 @@ async function postCode() {
       });
   }
 }
-
 postCode();