javascript-refactoring

JavaScript Code Refactoring Guide

Use this guide to refactor JavaScript into separate .cjs files in gh-aw.

Overview

gh-aw uses CommonJS modules (.cjs) for JavaScript in GitHub Actions workflows. These files are:

• Embedded in the Go binary using //go:embed directives
• Bundled using a custom JavaScript bundler that inlines local require() calls
• Executed in GitHub Actions using actions/github-script@v8

Top-Level Script Pattern

Top-level .cjs scripts executed directly in workflows follow this pattern:

✅ Correct Pattern - Export main, but don't call it:

async function main() {
  // Script logic here
  core.info("Running the script");
}

module.exports = { main };

❌ Incorrect Pattern - Don't call main in the file:

async function main() {
  // Script logic here
  core.info("Running the script");
}

await main(); // ❌ Don't do this!

module.exports = { main };

Why this pattern?

• The bundler automatically injects await main() during inline execution in GitHub Actions
• This allows the script to be both imported (for testing) and executed (in workflows)
• It provides a clean separation between module definition and execution
• It enables better testing by allowing tests to import and call main() with mocks

Examples of top-level scripts:

• create_issue.cjs - Creates GitHub issues
• add_comment.cjs - Adds comments to issues/PRs
• add_labels.cjs - Adds labels to issues/PRs
• update_project.cjs - Updates GitHub Projects

All of these files export main but do not call it directly.

Step 1: Create the New .cjs File

Create your new file in /home/runner/work/gh-aw/gh-aw/pkg/workflow/js/ with a descriptive name:

File naming convention:

• Use snake_case for filenames (e.g., sanitize_content.cjs, load_agent_output.cjs)
• Use .cjs extension (CommonJS module)
• Choose names that clearly describe the module's purpose

Example file structure:

// @ts-check
/// <reference types="@actions/github-script" />

/**
 * Brief description of what this module does
 */

/**
 * Function documentation
 * @param {string} input - Description of parameter
 * @returns {string} Description of return value
 */
function myFunction(input) {
  // Implementation
  return input;
}

// Export the function(s)
module.exports = {
  myFunction,
};