@ronaldphilipsen/local-action 0.0.0-stage → 7.0.1

package/CONTRIBUTING.md

@@ -0,0 +1,140 @@
+# Contributing
+
+All contributions are welcome and greatly appreciated! However, please try to
+keep them limited in scope so that they can be more easily reviewed.
+
+## Steps to Contribute
+
+> [!WARNING]
+>
+> Check the `engine` property in [`package.json`](./package.json) to see what
+> version of Node.js is required for local development. This can be different
+> from the version of Node.js used on the GitHub Actions runners. Tools like
+> [nodenv](https://github.com/nodenv/nodenv) can be used to manage your Node.js
+> version automatically.
+
+1. Fork this repository
+1. Clone your fork
+1. Install the dependencies with `npm install`
+1. Make and test your changes
+1. Commit your changes
+
+   Make sure to do the following when you commit your changes:
+   - Increase the version number in [`package.json`](./package.json)
+   - Run `npm install` to ensure dependencies are up to date
+   - Run `npm run all` to run formatting, linting, etc.
+
+1. Open a pull request back to this repository
+1. Notify the maintainers of this repository for peer review and approval
+1. Merge :tada:
+
+The maintainers of this repository will create a new release with your changes
+so that everyone can enjoy your contributions!
+
+## Testing
+
+This project requires **100%** test coverage.
+
+> [!IMPORTANT]
+>
+> It is critical that we have 100% test coverage to ensure that we are not
+> introducing any regressions. All changes will be throughly tested by
+> maintainers of this repository before a new release is created.
+
+### Testing Local Updates
+
+As you make changes, it's a great idea to run the `local-action` tool regularly
+against various repositories with different configurations.
+
+1. Symlink your package folder (this should only need to be done once)
+
+   ```bash
+   npm link
+   ```
+
+1. Test your updated version
+
+   ```bash
+   local-action run <path> <entrypoint> <dotenv file>
+
+   # Or...
+   npm exec local-action run <path> <entrypoint> <dotenv file>
+   ```
+
+Once you're finished testing, make sure to unlink!
+
+```bash
+npm unlink @github/local-action
+```
+
+#### Example Actions to Test
+
+After making updates and running the test suite, please also make sure to test
+your updates using the following GitHub Actions repositories:
+
+- [`actions/javascript-action`](https://github.com/actions/javascript-action)
+- [`actions/typescript-action`](https://github.com/actions/typescript-action)
+
+1. Clone each repository locally
+1. From your `github/local-action` fork, test each action
+
+   ```bash
+   npm exec local-action \
+   "/<action repository clone path>/typescript-action" \
+   "src/main.ts" \
+   "<path to your .env file>"
+
+   npm exec local-action \
+   "/<action repository clone path>/javascript-action" \
+   "src/main.ts" \
+   "<path to your .env file>"
+   ```
+
+   For an example `.env` file to use for testing, see
+   [`.env.example`](./.env.example).
+
+### Running the Test Suite
+
+Simply run the following command to invoke the entire test suite:
+
+```bash
+npm run test
+```
+
+> [!NOTE]
+>
+> This requires that you have already run `npm install`
+
+### Toolkit Stub Updates
+
+When updating any of the supported stubs for the GitHub Actions Toolkit, please
+make sure to also update the following. This helps ensure that we are using the
+latest supported versions of the toolkit packages, and makes comparing changes
+across commits easier.
+
+1. The supported version in the [`README.md`](./README.md)
+
+   ```markdown
+   | Package                                                                | Version  |
+   | ---------------------------------------------------------------------- | -------- |
+   | [`@actions/artifact`](https://www.npmjs.com/package/@actions/artifact) | `2.3.2`  |
+   | [`@actions/core`](https://www.npmjs.com/package/@actions/core)         | `1.11.1` |
+   | [`@actions/github`](https://www.npmjs.com/package/@actions/github)     | `6.0.1`  |
+   ```
+
+1. The latest reviewed commit URL in the corresponding `src/stubs/*.ts` file
+
+   ```typescript
+   /**
+    * Last Reviewed Commit: https://github.com/actions/toolkit/blob/f58042f9cc16bcaa87afaa86c2974a8c771ce1ea/packages/artifact/src/artifact.ts
+    * Last Reviewed Date: 2025-09-10
+    */
+   ```
+
+When comparing commits to see what has been updated in the toolkit packages, be
+sure to compare against the last reviewed commit in the corresponding stub file.
+This can be done more easily using the following URL format:
+
+```plain
+https://github.com/actions/toolkit/compare/<old commit>..main
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,278 @@
-# Temporary Holding Version
+# Local Action Debugger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![GitHub Super-Linter](https://github.com/github/local-action/actions/workflows/linter.yml/badge.svg)
+![Continuous Integration](https://github.com/github/local-action/actions/workflows/continuous-integration.yml/badge.svg)
+![Code Coverage](badges/coverage.svg)
+
+Run custom GitHub Actions locally and test them in Visual Studio Code!
+
+This command-line tool emulates some **basic** functionality of the
+[GitHub Actions Toolkit](https://github.com/actions/toolkit) so that custom
+actions can be run directly on your workstation.
+
+> [!NOTE]
+>
+> This tool currently only supports JavaScript and TypeScript actions!
+
+The following table tracks the versions of the GitHub Actions Toolkit that are
+currently implemented by this tool.
+
+| Package                                                                | Version |
+| ---------------------------------------------------------------------- | ------- |
+| [`@actions/artifact`](https://www.npmjs.com/package/@actions/artifact) | `5.0.2` |
+| [`@actions/cache`](https://www.npmjs.com/package/@actions/cache)       | `5.0.3` |
+| [`@actions/core`](https://www.npmjs.com/package/@actions/core)         | `2.0.2` |
+| [`@actions/github`](https://www.npmjs.com/package/@actions/github)     | `7.0.0` |
+
+## Changelog
+
+See the [CHANGELOG](./CHANGELOG.md) for a complete list of changes.
+
+## Node.js Version Support
+
+This tool is currently tested against **Node.js versions 22 and 24**. It is not
+guaranteed to work with other versions at this time.
+
+## Package Manager Support
+
+### `npm` Support
+
+This tool is designed primarily for use with `npm` and `npx`. It is recommended
+to use `npm` for managing actions you wish to test with this tool.
+
+### `pnpm` Support
+
+This tool ships with **experimental** support for `pnpm`. If you encounter any
+issues, please [file an issue](https://github.com/github/local-action/issues).
+
+Some caveats to this support are listed below.
+
+- This tool does not support CommonJS actions using `pnpm`.
+
+### `yarn` Support
+
+This tool ships with **experimental** support for `yarn`. If you encounter any
+issues, please [file an issue](https://github.com/github/local-action/issues).
+
+Some caveats to this support are listed below.
+
+- The `@github/local-action` package should be run using
+  `yarn dlx @github/local-action` instead of `yarn local-action`.
+- This tool does not support CommonJS actions using `yarn`.
+
+## Prerequisites
+
+### Installed Tools
+
+- [Node.js and npm](https://nodejs.org/en)
+
+### Action Structure
+
+For JavaScript and TypeScript actions, your code should follow the format of the
+corresponding template repository.
+
+- [`actions/javascript-action`](https://github.com/actions/javascript-action)
+- [`actions/typescript-action`](https://github.com/actions/typescript-action)
+
+Specifically, there should be a separation between the entrypoint used by GitHub
+Actions when invoking your code, and the actual logic of your action. For
+example:
+
+#### Entrypoint: **`index.ts`**
+
+This is what is invoked by GitHub Actions when your action is run.
+
+```typescript
+/**
+ * This file is the entrypoint for the action
+ */
+import { run } from './main'
+
+// It calls the actual logic of the action
+run()
+```
+
+#### Logic: **`main.ts`**
+
+This is the actual implementation of your action. It is called by the
+entrypoint.
+
+```typescript
+import * as core from '@actions/core'
+import { wait } from './wait'
+
+/**
+ * This file is the actual logic of the action
+ * @returns {Promise<void>} Resolves when the action is complete
+ */
+export async function run(): Promise<void> {
+  // ...
+}
+```
+
+### Transpiled Actions
+
+Depending on how you build your JavaScript/TypeScript actions, you may do one of
+the following when preparing for release:
+
+- Commit the `node_modules` directory to your repository
+- Transpile your code and dependencies using tools like
+  [`tsc`](https://www.typescriptlang.org/docs/handbook/compiler-options.html),
+  [`@vercel/ncc`](https://www.npmjs.com/package/@vercel/ncc), or
+  [`rollup`](https://rollupjs.org/)
+
+**This tool supports non-transpiled action code only.** This is because it uses
+[`quibble`](https://github.com/testdouble/quibble) to override GitHub Actions
+Toolkit dependencies (e.g
+[`@actions/core`](https://www.npmjs.com/package/@actions/core)). In transpiled
+code, this simply doesn't work.
+
+For example, if you have a TypeScript action that follows the same format as the
+[template](https://github.com/actions/typescript-action), you would have both
+`src` and `dist` directories in your repository. The `dist` directory contains
+the transpiled code with any dependencies included. When running this utility,
+you will want to target the code files in the `src` directory instead (including
+the dependencies this tool wants to replace). This has the added benefit of
+being able to hook into debugging utilities in your IDE :tada:
+
+For additional information about transpiled action code, see
+[Commit, tag, and push your action to GitHub](https://docs.github.com/en/actions/creating-actions/creating-a-javascript-action#commit-tag-and-push-your-action-to-github).
+
+## Installation
+
+### Option 1: Install from npm
+
+1. Install via `npm`
+
+   ```bash
+   npm i -g @github/local-action
+   ```
+
+### Option 2: Clone this Repository
+
+1. Clone this repository locally
+
+   ```bash
+   git clone https://github.com/github/local-action.git
+   ```
+
+1. Install dependencies
+
+   ```bash
+   npm ci
+   ```
+
+1. Install via `npm`
+
+   ```bash
+   npm i -g .
+   ```
+
+   Alternatively, you can link the package if you want to make code changes
+
+   ```bash
+   npm link .
+   ```
+
+## Commands
+
+### `local-action`
+
+| Option            | Description                 |
+| ----------------- | --------------------------- |
+| `-h`, `--help`    | Display help information    |
+| `-V`, `--version` | Display version information |
+
+### `local-action run <path> <logic entrypoint> <dotenv file> [--pre <pre entrypoint>] [--post <post entrypoint>]`
+
+| Argument                   | Description                                                         |
+| -------------------------- | ------------------------------------------------------------------- |
+| `path`                     | Path to the local action directory                                  |
+|                            | Example: `/path/to/action.yml`                                      |
+| `logic entrypoint`         | Action logic entrypoint (relative to action directory)              |
+|                            | Example: `src/main.ts`                                              |
+| `dotenv file`              | Path to the local `.env` file for action inputs                     |
+|                            | Example: `/path/to/.env`                                            |
+|                            | See the example [`.env.example`](.env.example)                      |
+| `--pre <pre entrypoint>`   | (Optional) `pre` command entrypoint (relative to action directory)  |
+|                            | Example: `pre/main.ts`                                              |
+| `--post <post entrypoint>` | (Optional) `post` command entrypoint (relative to action directory) |
+|                            | Example: `post/main.ts`                                             |
+
+Examples:
+
+```bash
+local-action run /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
+
+# The `run` action is invoked by default as well
+local-action /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
+```
+
+#### Output
+
+```console
+$ local-action run /path/to/typescript-action src/main.ts .env --pre pre/main.ts --post post/main.ts
+     _        _   _               ____       _
+    / \   ___| |_(_) ___  _ __   |  _ \  ___| |__  _   _  __ _  __ _  ___ _ __
+   / _ \ / __| __| |/ _ \| '_ \  | | | |/ _ \ '_ \| | | |/ _` |/ _` |/ _ \ '__|
+  / ___ \ (__| |_| | (_) | | | | | |_| |  __/ |_) | |_| | (_| | (_| |  __/ |
+ /_/   \_\___|\__|_|\___/|_| |_| |____/ \___|_.__/ \__,_|\__, |\__, |\___|_|
+                                                         |___/ |___/
+================================================================================
+                                 Configuration
+================================================================================
+
+┌─────────┬────────────────────┬───────────────────────────────────────────┐
+│ (index) │       Field        │                  Value                    │
+├─────────┼────────────────────┼───────────────────────────────────────────┤
+│    0    │   'Action Path'    │       '/path/to/typescript-action'        │
+│    1    │    'Entrypoint'    │ '/path/to/typescript-action/src/main.ts'  │
+│    2    │ 'Environment File' │   '/path/to/local-action-debugger/.env'   │
+└─────────┴────────────────────┴───────────────────────────────────────────┘
+
+================================================================================
+                                Action Metadata
+================================================================================
+
+┌─────────┬────────────────┬───────────────────────────────┐
+│ (index) │     Input      │          Description          │
+├─────────┼────────────────┼───────────────────────────────┤
+│    0    │ 'milliseconds' │ 'Your input description here' │
+└─────────┴────────────────┴───────────────────────────────┘
+
+┌─────────┬────────┬────────────────────────────────┐
+│ (index) │ Output │          Description           │
+├─────────┼────────┼────────────────────────────────┤
+│    0    │ 'time' │ 'Your output description here' │
+└─────────┴────────┴────────────────────────────────┘
+
+================================================================================
+                                 Running Action
+================================================================================
+```
+
+## (TypeScript) TSConfig Requirements
+
+If you are testing TypeScript actions, there are a few settings that **must** be
+configured in your `tsconfig.json` file (either explicitly or via their default
+values).
+
+| Property                                                      | Required Value |
+| ------------------------------------------------------------- | -------------- |
+| [`allowJs`](https://www.typescriptlang.org/tsconfig/#allowJs) | `false`        |
+
+### Troubleshooting
+
+Possible errors that can arise from not having `allowJs: false`:
+
+- `TypeError [ERR_INVALID_URL_SCHEME]: The URL must be of scheme file` from tsx
+  when trying to run `npx @github/local-action`.
+
+## Features
+
+The following list links to documentation on how to use various features of the
+`local-action` tool.
+
+- [Supported Functionality](./docs//supported-functionality.md)
+- [Debugging in Visual Studio Code](./docs/debugging-in-vscode.md)
+- [Create a Job Summary](./docs/create-a-job-summary.md)

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security
+
+Thanks for helping make GitHub safe for everyone!
+
+GitHub takes the security of our software products and services seriously,
+including all of the open source code repositories managed through our GitHub
+organizations, such as [GitHub](https://github.com/GitHub).
+
+Even though
+[open source repositories are outside of the scope of our bug bounty program](https://bounty.github.com/index.html#scope)
+and therefore not eligible for bounty rewards, we will ensure that your finding
+gets passed along to the appropriate maintainers for remediation.
+
+## Reporting Security Issues
+
+If you believe you have found a security vulnerability in any GitHub-owned
+repository, please report it to us through coordinated disclosure.
+
+**Please do not report security vulnerabilities through public GitHub issues,
+discussions, or pull requests.**
+
+Instead, please send an email to
+[opensource-security@github.com](mailto:opensource-security@github.com).
+
+Please include as much of the information listed below as you can to help us
+better understand and resolve the issue:
+
+- The type of issue (e.g., buffer overflow, SQL injection, or cross-site
+  scripting)
+- Full paths of source file(s) related to the manifestation of the issue
+- The location of the affected source code (tag/branch/commit or direct URL)
+- Any special configuration required to reproduce the issue
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+## Policy
+
+See
+[GitHub's Safe Harbor Policy](https://docs.github.com/en/site-policy/security-policies/github-bug-bounty-program-legal-safe-harbor#1-safe-harbor-terms)

package/SUPPORT.md

@@ -0,0 +1,19 @@
+# Support
+
+## How to Get Help
+
+This project uses GitHub issues to track bugs and feature requests. Please
+search the existing issues before filing new issues to avoid duplicates. For new
+issues, file your bug or feature request as a new issue.
+
+For help or questions about using this project, please feel free to submit an
+issue as well.
+
+This project is under development and maintained by GitHub staff and the
+community, however availability is limited . We will do our best to respond to
+support, feature requests, and community questions in a timely manner, but there
+is no "official" support for this project at this time.
+
+## GitHub Support Policy
+
+Support for this project is limited to the resources listed above.

package/__fixtures__/@actions/core.ts

@@ -0,0 +1,14 @@
+import { jest } from '@jest/globals'
+
+export const debug = jest.fn().mockImplementation(() => {})
+export const error = jest.fn().mockImplementation(() => {})
+export const info = jest.fn().mockImplementation(() => {})
+export const isDebug = jest.fn().mockImplementation(() => false)
+export const getInput = jest.fn().mockImplementation(() => {})
+export const setOutput = jest.fn().mockImplementation(() => {})
+export const setFailed = jest.fn().mockImplementation(() => {})
+export const warning = jest.fn().mockImplementation(() => {})
+export const summary = {
+  addRaw: jest.fn().mockImplementation(() => {}),
+  write: jest.fn().mockImplementation(() => {})
+}

package/__fixtures__/@actions/exec.ts

@@ -0,0 +1,9 @@
+import { jest } from '@jest/globals'
+
+export const exec = jest.fn().mockImplementation(() => {})
+export const getExecOutput = jest.fn().mockImplementation(() => {})
+
+export default {
+  exec,
+  getExecOutput
+}

package/__fixtures__/@actions/github.ts

@@ -0,0 +1,3 @@
+import * as octokit from '../@octokit/rest.js'
+
+export const getOctokit = () => octokit

package/__fixtures__/@actions/http-client.ts

@@ -0,0 +1,9 @@
+import { jest } from '@jest/globals'
+
+export const getAgent = jest.fn()
+export const getAgentDispatcher = jest.fn()
+
+export class HttpClient {
+  getAgent = getAgent
+  getAgentDispatcher = getAgentDispatcher
+}

package/__fixtures__/@actions/io.ts

@@ -0,0 +1,9 @@
+import { jest } from '@jest/globals'
+
+export const which = jest.fn().mockImplementation(() => {})
+export const mkdirP = jest.fn().mockImplementation(() => {})
+
+export default {
+  which,
+  mkdirP
+}

package/__fixtures__/@octokit/rest.ts

@@ -0,0 +1,18 @@
+import { jest } from '@jest/globals'
+import { Endpoints } from '@octokit/types'
+
+export const graphql = jest.fn()
+export const paginate = jest.fn()
+export const request = jest.fn()
+export const rest = {
+  actions: {
+    deleteArtifact:
+      jest.fn<
+        () => Endpoints['DELETE /repos/{owner}/{repo}/actions/artifacts/{artifact_id}']['response']
+      >(),
+    listWorkflowRunArtifacts:
+      jest.fn<
+        () => Endpoints['GET /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts']['response']
+      >()
+  }
+}

package/__fixtures__/crypto.ts

@@ -0,0 +1,7 @@
+import { jest } from '@jest/globals'
+
+export const createHash = jest.fn()
+
+export default {
+  createHash
+}

package/__fixtures__/fs.ts

@@ -0,0 +1,27 @@
+import { jest } from '@jest/globals'
+
+export const accessSync = jest.fn()
+export const copyFileSync = jest.fn()
+export const createWriteStream = jest.fn()
+export const createReadStream = jest.fn()
+export const existsSync = jest.fn()
+export const mkdirSync = jest.fn()
+export const readdirSync = jest.fn()
+export const readFileSync = jest.fn()
+export const rmSync = jest.fn()
+export const statSync = jest.fn()
+export const writeFileSync = jest.fn()
+
+export default {
+  accessSync,
+  copyFileSync,
+  createWriteStream,
+  createReadStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync
+}

package/__fixtures__/javascript/no-export/.env.fixture

@@ -0,0 +1,2 @@
+ACTIONS_STEP_DEBUG=false
+INPUT_MILLISECONDS=2400

package/__fixtures__/javascript/no-export/action.yml

@@ -0,0 +1,16 @@
+name: JavaScript (No Import)
+description: This action doesn't import any dependencies
+
+inputs:
+  myInput:
+    description: An input
+    required: true
+    default: value
+
+outputs:
+  myOutput:
+    description: An output
+
+runs:
+  using: node20
+  main: dist/index.js

package/__fixtures__/javascript/no-export/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "javascript-action",
+  "description": "GitHub Actions JavaScript template",
+  "version": "0.0.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@actions/core": "^2.0.2"
+  },
+  "devDependencies": {}
+}

package/__fixtures__/javascript/no-import/.env.fixture

@@ -0,0 +1,2 @@
+ACTIONS_STEP_DEBUG=false
+INPUT_MILLISECONDS=2400

package/__fixtures__/javascript/no-import/action.yml

@@ -0,0 +1,16 @@
+name: JavaScript (No Import)
+description: This action doesn't import any dependencies
+
+inputs:
+  myInput:
+    description: An input
+    required: true
+    default: value
+
+outputs:
+  myOutput:
+    description: An output
+
+runs:
+  using: node20
+  main: dist/index.js