actions-up 0.0.1 → 1.0.0

package/dist/core/scan-github-actions.js

@@ -0,0 +1,116 @@
+import { ACTIONS_DIRECTORY, GITHUB_DIRECTORY, WORKFLOWS_DIRECTORY } from "./constants.js";
+import { scanWorkflowFile } from "./scan-workflow-file.js";
+import { scanActionFile } from "./scan-action-file.js";
+import { isYamlFile } from "./fs/is-yaml-file.js";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+async function scanGitHubActions(rootPath = process.cwd()) {
+	let result = {
+		compositeActions: /* @__PURE__ */ new Map(),
+		workflows: /* @__PURE__ */ new Map(),
+		actions: []
+	};
+	let normalizedRoot = resolve(rootPath);
+	function isWithin(root, candidate) {
+		let relativePath = relative(root, candidate);
+		return relativePath !== "" && !relativePath.startsWith("..") && !isAbsolute(relativePath);
+	}
+	let githubPath = join(normalizedRoot, GITHUB_DIRECTORY);
+	if (!isWithin(normalizedRoot, githubPath)) throw new Error("Invalid path: detected path traversal attempt");
+	function isValidName(name) {
+		if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+			console.warn(`Skipping invalid name: ${name}`);
+			return false;
+		}
+		return true;
+	}
+	let workflowsPath = join(githubPath, WORKFLOWS_DIRECTORY);
+	if (!isWithin(normalizedRoot, workflowsPath)) return result;
+	try {
+		let workflowsStat = await stat(workflowsPath);
+		if (workflowsStat.isDirectory()) {
+			let files = await readdir(workflowsPath);
+			let workflowPromises = files.filter((file) => {
+				if (!isValidName(file)) return false;
+				return isYamlFile(file);
+			}).map(async (file) => {
+				let filePath = join(workflowsPath, file);
+				if (!isWithin(workflowsPath, filePath)) {
+					console.warn(`Skipping file outside workflows directory: ${file}`);
+					return {
+						success: false,
+						actions: [],
+						path: ""
+					};
+				}
+				try {
+					let actions = await scanWorkflowFile(filePath);
+					return {
+						path: `${GITHUB_DIRECTORY}/${WORKFLOWS_DIRECTORY}/${file}`,
+						success: true,
+						actions
+					};
+				} catch {
+					return {
+						path: `${GITHUB_DIRECTORY}/${WORKFLOWS_DIRECTORY}/${file}`,
+						success: false,
+						actions: []
+					};
+				}
+			});
+			let workflowResults = await Promise.all(workflowPromises);
+			for (let workflow of workflowResults) if (workflow.success && workflow.path) if (workflow.actions.length > 0) {
+				result.workflows.set(workflow.path, workflow.actions);
+				result.actions.push(...workflow.actions);
+			} else result.workflows.set(workflow.path, []);
+		}
+	} catch {}
+	let actionsPath = join(githubPath, ACTIONS_DIRECTORY);
+	if (!isWithin(normalizedRoot, actionsPath)) return result;
+	try {
+		let actionsStat = await stat(actionsPath);
+		if (actionsStat.isDirectory()) {
+			let subdirectories = await readdir(actionsPath);
+			let actionPromises = subdirectories.map(async (subdir) => {
+				if (!isValidName(subdir)) return null;
+				let subdirPath = join(actionsPath, subdir);
+				if (!isWithin(actionsPath, subdirPath)) {
+					console.warn(`Skipping subdirectory outside actions path: ${subdir}`);
+					return null;
+				}
+				try {
+					let subdirectoryStat = await stat(subdirPath);
+					if (!subdirectoryStat.isDirectory()) return null;
+					let actionFilePath = join(subdirPath, "action.yml");
+					if (!isWithin(subdirPath, actionFilePath)) return null;
+					let actions = [];
+					try {
+						actions = await scanActionFile(actionFilePath);
+					} catch {
+						try {
+							actionFilePath = join(subdirPath, "action.yaml");
+							if (!isWithin(subdirPath, actionFilePath)) return null;
+							actions = await scanActionFile(actionFilePath);
+						} catch {
+							return null;
+						}
+					}
+					return {
+						path: `${GITHUB_DIRECTORY}/${ACTIONS_DIRECTORY}/${subdir}`,
+						name: subdir,
+						actions
+					};
+				} catch {
+					return null;
+				}
+			});
+			let actionResults = await Promise.all(actionPromises);
+			for (let actionResult of actionResults) if (actionResult) {
+				result.compositeActions.set(actionResult.name, actionResult.path);
+				result.actions.push(...actionResult.actions);
+			}
+		}
+	} catch {}
+	return result;
+}
+export { scanGitHubActions };

package/dist/core/scan-workflow-file.d.ts

@@ -0,0 +1,9 @@
+import { GitHubAction } from '../types/github-action';
+/**
+ * Scans a GitHub workflow file for all action references.
+ *
+ * @param filePath - The path to the workflow YAML file to scan.
+ * @returns A promise that resolves to an array of GitHubAction objects found in
+ *   the workflow.
+ */
+export declare function scanWorkflowFile(filePath: string): Promise<GitHubAction[]>;

package/dist/core/scan-workflow-file.js

@@ -0,0 +1,7 @@
+import { scanWorkflowAst } from "./ast/scanners/scan-workflow-ast.js";
+import { readYamlDocument } from "./fs/read-yaml-document.js";
+async function scanWorkflowFile(filePath) {
+	let { document, content } = await readYamlDocument(filePath);
+	return scanWorkflowAst(document, content, filePath);
+}
+export { scanWorkflowFile };

package/dist/core/schema/composite/is-composite-action-runs.d.ts

@@ -0,0 +1,8 @@
+import { CompositeActionRuns } from '../../../types/composite-action-runs';
+/**
+ * Type guard to check if a value conforms to the CompositeActionRuns interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid runs configuration.
+ */
+export declare function isCompositeActionRuns(value: unknown): value is CompositeActionRuns;

package/dist/core/schema/composite/is-composite-action-runs.js

@@ -0,0 +1,6 @@
+function isCompositeActionRuns(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	let object = value;
+	return "using" in object;
+}
+export { isCompositeActionRuns };

package/dist/core/schema/composite/is-composite-action-step.d.ts

@@ -0,0 +1,8 @@
+import { CompositeActionStep } from '../../../types/composite-action-step';
+/**
+ * Type guard to check if a value conforms to the CompositeActionStep interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid composite action step.
+ */
+export declare function isCompositeActionStep(value: unknown): value is CompositeActionStep;

package/dist/core/schema/composite/is-composite-action-structure.d.ts

@@ -0,0 +1,9 @@
+import { CompositeActionStructure } from '../../../types/composite-action-structure';
+/**
+ * Type guard to check if a value conforms to the CompositeActionStructure
+ * interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid composite action structure.
+ */
+export declare function isCompositeActionStructure(value: unknown): value is CompositeActionStructure;

package/dist/core/schema/composite/is-composite-action-structure.js

@@ -0,0 +1,6 @@
+function isCompositeActionStructure(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	let object = value;
+	return "name" in object || "description" in object || "runs" in object;
+}
+export { isCompositeActionStructure };

package/dist/core/schema/workflow/is-workflow-job.d.ts

@@ -0,0 +1,8 @@
+import { WorkflowJob } from '../../../types/workflow-job';
+/**
+ * Type guard to check if a value conforms to the WorkflowJob interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid workflow job.
+ */
+export declare function isWorkflowJob(value: unknown): value is WorkflowJob;

package/dist/core/schema/workflow/is-workflow-step.d.ts

@@ -0,0 +1,8 @@
+import { WorkflowStep } from '../../../types/workflow-step';
+/**
+ * Type guard to check if a value conforms to the WorkflowStep interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid workflow step.
+ */
+export declare function isWorkflowStep(value: unknown): value is WorkflowStep;

package/dist/core/schema/workflow/is-workflow-structure.d.ts

@@ -0,0 +1,8 @@
+import { WorkflowStructure } from '../../../types/workflow-structure';
+/**
+ * Type guard to check if a value conforms to the WorkflowStructure interface.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a valid workflow structure.
+ */
+export declare function isWorkflowStructure(value: unknown): value is WorkflowStructure;

package/dist/core/schema/workflow/is-workflow-structure.js

@@ -0,0 +1,6 @@
+function isWorkflowStructure(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	let object = value;
+	return "on" in object || "name" in object || "jobs" in object;
+}
+export { isWorkflowStructure };

package/dist/package.js

@@ -0,0 +1,2 @@
+const version = "1.0.0";
+export { version };

package/dist/types/action-update.d.ts

@@ -0,0 +1,21 @@
+import { GitHubAction } from './github-action';
+/** Update information for a GitHub Action. */
+export interface ActionUpdate {
+  /** Current version string. */
+  currentVersion: string | null
+
+  /** Latest available version. */
+  latestVersion: string | null
+
+  /** SHA hash of the latest version. */
+  latestSha: string | null
+
+  /** The original action from scanning. */
+  action: GitHubAction
+
+  /** Whether this is a major version change. */
+  isBreaking: boolean
+
+  /** Whether an update is available. */
+  hasUpdate: boolean
+}

package/dist/types/composite-action-runs.d.ts

@@ -0,0 +1,12 @@
+import { CompositeActionStep } from './composite-action-step';
+/** Represents the runs configuration for a composite action. */
+export interface CompositeActionRuns {
+  /** Array of steps to execute. */
+  steps?: CompositeActionStep[]
+
+  /** Allow additional properties. */
+  [key: string]: unknown
+
+  /** Must be 'composite' for composite actions. */
+  using?: string
+}

package/dist/types/composite-action-step.d.ts

@@ -0,0 +1,23 @@
+/** Represents a step in a composite GitHub Action. */
+export interface CompositeActionStep {
+  /** Environment variables for this step. */
+  env?: Record<string, unknown>
+
+  /** Working directory for the step. */
+  'working-directory'?: string
+
+  /** Allow additional properties. */
+  [key: string]: unknown
+
+  /** Shell to use for the run command. */
+  shell?: string
+
+  /** Action to use for this step. */
+  uses?: string
+
+  /** Display name for this step. */
+  name?: string
+
+  /** Shell command to run for this step. */
+  run?: string
+}

package/dist/types/composite-action-structure.d.ts

@@ -0,0 +1,21 @@
+import { CompositeActionRuns } from './composite-action-runs';
+/** Represents the structure of a composite GitHub Action file. */
+export interface CompositeActionStructure {
+  /** Output values from the action. */
+  outputs?: Record<string, unknown>
+
+  /** Input parameters for the action. */
+  inputs?: Record<string, unknown>
+
+  /** Runs configuration for composite actions. */
+  runs?: CompositeActionRuns
+
+  /** Allow additional properties. */
+  [key: string]: unknown
+
+  /** Description of what the action does. */
+  description?: string
+
+  /** Display name of the action. */
+  name?: string
+}

package/dist/types/github-action.d.ts

@@ -0,0 +1,23 @@
+/** Represents a GitHub Action used in workflows or composite actions. */
+export interface GitHubAction {
+  /** Type of the GitHub Action. */
+  type: 'composite' | 'external' | 'docker' | 'local'
+
+  /** Version or tag of the action (e.g., 'v1', 'main', commit SHA). */
+  version?: string | null
+
+  /** Line number where the action is used in the file. */
+  line?: number
+
+  /** Path to the file where this action is used. */
+  file?: string
+
+  /** Original `uses` string from workflow, if available. */
+  uses?: string
+
+  /** Full name of the action (e.g., 'actions/checkout'). */
+  name: string
+
+  /** Original `ref` string from workflow, if available. */
+  ref?: string
+}

package/dist/types/scan-result.d.ts

@@ -0,0 +1,12 @@
+import { GitHubAction } from './github-action';
+/** Result of scanning a repository for GitHub Actions usage. */
+export interface ScanResult {
+  /** Map of workflow files to their used GitHub Actions. */
+  workflows: Map<string, GitHubAction[]>
+
+  /** Map of composite action names to their file paths. */
+  compositeActions: Map<string, string>
+
+  /** List of all unique GitHub Actions found in the repository. */
+  actions: GitHubAction[]
+}

package/dist/types/workflow-job.d.ts

@@ -0,0 +1,18 @@
+import { WorkflowStep } from './workflow-step';
+/** Represents a job in a GitHub Actions workflow. */
+export interface WorkflowJob {
+  /** Runner environment(s) to execute this job on (e.g., 'ubuntu-latest'). */
+  'runs-on'?: string[] | string
+
+  /** Job IDs that must complete successfully before this job runs. */
+  needs?: string[] | string
+
+  /** Array of steps to execute in this job. */
+  steps?: WorkflowStep[]
+
+  /** Allow additional properties for job configuration. */
+  [key: string]: unknown
+
+  /** Conditional expression to determine if the job should run. */
+  if?: string
+}

package/dist/types/workflow-step.d.ts

@@ -0,0 +1,20 @@
+/** Represents a single step in a GitHub Actions workflow job. */
+export interface WorkflowStep {
+  /** Input parameters to pass to the action. */
+  with?: Record<string, unknown>
+
+  /** Environment variables to set for this step. */
+  env?: Record<string, unknown>
+
+  /** Allow additional properties for step configuration. */
+  [key: string]: unknown
+
+  /** Action to use for this step (e.g., 'actions/checkout@v4'). */
+  uses?: string
+
+  /** Display name for this step. */
+  name?: string
+
+  /** Shell command to run for this step. */
+  run?: string
+}

package/dist/types/workflow-structure.d.ts

@@ -0,0 +1,15 @@
+import { WorkflowJob } from './workflow-job';
+/** Represents the root structure of a GitHub Actions workflow file. */
+export interface WorkflowStructure {
+  /** Map of job IDs to job configurations. */
+  jobs?: Record<string, WorkflowJob>
+
+  /** Allow additional properties for workflow configuration. */
+  [key: string]: unknown
+
+  /** Display name for the workflow. */
+  name?: string
+
+  /** Events that trigger the workflow (push, pull_request, etc.). */
+  on?: unknown
+}

package/license.md

@@ -0,0 +1,20 @@
+# The MIT License (MIT)
+
+Copyright 2025 Azat S. <to@azat.io>
+
+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/package.json

@@ -1,4 +1,55 @@
 {
   "name": "actions-up",
-  "version": "0.0.1"
+  "version": "1.0.0",
+  "description": "Interactive CLI tool to update GitHub Actions to latest versions with SHA pinning",
+  "keywords": [
+    "github-actions",
+    "actions",
+    "updater",
+    "cli",
+    "workflow",
+    "ci-cd",
+    "security",
+    "sha",
+    "dependencies",
+    "update"
+  ],
+  "homepage": "https://github.com/azat-io/actions-up",
+  "repository": "azat-io/actions-up",
+  "license": "MIT",
+  "author": "Azat S. <to@azat.io>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "bin": {
+    "actions-up": "./bin/actions-up.js"
+  },
+  "files": [
+    "./bin",
+    "./dist"
+  ],
+  "dependencies": {
+    "@octokit/graphql": "^9.0.1",
+    "cac": "^6.7.14",
+    "enquirer": "^2.4.1",
+    "nanospinner": "^1.2.2",
+    "picocolors": "^1.1.1",
+    "semver": "^7.7.2",
+    "yaml": "^2.8.1"
+  },
+  "engines": {
+    "node": "^18.0.0 || >=20.0.0"
+  },
+  "pnpm": {
+    "overrides": {
+      "vite": "npm:rolldown-vite@latest"
+    }
+  }
 }

package/readme.md

@@ -0,0 +1,175 @@
+# Actions Up!
+
+<img
+  src="https://raw.githubusercontent.com/azat-io/actions-up/main/assets/logo.svg"
+  alt="Actions Up! logo"
+  width="160"
+  height="160"
+  align="right"
+/>
+
+[![Version](https://img.shields.io/npm/v/actions-up.svg?color=fff&labelColor=4493f8)](https://npmjs.com/package/actions-up)
+[![Code Coverage](https://img.shields.io/codecov/c/github/azat-io/actions-up.svg?color=fff&labelColor=4493f8)](https://codecov.io/gh/azat-io/actions-up)
+[![GitHub License](https://img.shields.io/badge/license-MIT-232428.svg?color=fff&labelColor=4493f8)](https://github.com/azat-io/actions-up/blob/main/license.md)
+
+Actions Up scans your workflows and composite actions to discover every referenced GitHub Action, then checks for newer releases.
+
+Interactively upgrade and pin actions to exact commit SHAs for secure, reproducible CI and low‑friction maintenance.
+
+## Features
+
+- **Auto-discovery**: Scans all workflows (`.github/workflows/*.yml`) and composite actions (`.github/actions/*/action.yml`)
+- **SHA Pinning**: Updates actions to use commit SHA instead of tags for better security
+- **Batch Updates**: Update multiple actions at once
+- **Interactive Selection**: Choose which actions to update
+- **Breaking Changes Detection**: Warns about major version updates
+- **Fast & Efficient**: Parallel processing with optimized API calls
+
+###
+
+<br>
+
+<picture>
+  <source
+    srcset="https://raw.githubusercontent.com/azat-io/actions-up/main/assets/example-light.webp"
+    media="(prefers-color-scheme: light)"
+  />
+  <source
+    srcset="https://raw.githubusercontent.com/azat-io/actions-up/main/assets/example-dark.webp"
+    media="(prefers-color-scheme: dark)"
+  />
+  <img
+    src="https://raw.githubusercontent.com/azat-io/actions-up/main/assets/example-light.webp"
+    alt="Actions Up interactive example"
+    width="820"
+  />
+</picture>
+
+## Why
+
+### The Problem
+
+Keeping GitHub Actions updated is a critical but tedious task:
+
+- **Security Risk**: Using outdated actions with known vulnerabilities
+- **Manual Hell**: Checking dozens of actions across multiple workflows by hand
+- **Version Tags Are Mutable**: v1 or v2 tags can change without notice, breaking reproducibility
+- **Time Sink**: Hours spent on maintenance that could be used for actual development
+
+### The Solution
+
+Actions Up transforms a painful manual process into a delightful experience:
+
+| Without Actions Up             | With Actions Up                  |
+| :----------------------------- | :------------------------------- |
+| Check each action manually     | Scan all workflows in seconds    |
+| Risk using vulnerable versions | SHA pinning for maximum security |
+| 30+ minutes per repository     | Under 1 minute total             |
+
+## GitHub Token Required
+
+> **Important**: GitHub API has strict rate limits (60 requests/hour without token vs 5000 with token).
+> A GitHub token is **practically required** for using Actions Up.
+
+### Quick Token Setup
+
+[Create a GitHub Personal Access Token](https://github.com/settings/tokens/new?scopes=public_repo&description=actions-up).
+
+- For public repositories: Select `public_repo` scope
+- For private repositories: Select `repo` scope
+
+## Installation
+
+Quick use (no installation)
+
+```bash
+npx actions-up
+```
+
+Global installation
+
+```bash
+npm install -g actions-up
+```
+
+Per-project
+
+```bash
+npm install --save-dev actions-up
+```
+
+## Usage
+
+### Interactive Mode (Default)
+
+Run in your repository root with GitHub token:
+
+```bash
+GITHUB_TOKEN=ghp_xxxx npx actions-up
+```
+
+This will:
+
+1. Scan all `.github/workflows/*.yml` and `.github/actions/*/action.yml` files
+2. Check for available updates
+3. Show an interactive list to select updates
+4. Apply selected updates with SHA pinning
+
+### Auto-Update Mode
+
+Skip all prompts and update everything:
+
+```bash
+GITHUB_TOKEN=ghp_xxxx npx actions-up --yes
+# or
+GITHUB_TOKEN=ghp_xxxx npx actions-up -y
+```
+
+## Pro Tips
+
+### Shell Aliases
+
+Add to your `.zshrc`, `.bashrc` or `.config/fish/config.fish`:
+
+```bash
+# Basic alias with token from environment
+export GITHUB_TOKEN=ghp_xxxx  # Add this once to your shell config
+alias actions-up='GITHUB_TOKEN=$GITHUB_TOKEN npx actions-up'
+
+# With token from file
+alias actions-up='GITHUB_TOKEN=$(cat ~/.github-token) npx actions-up'
+
+# With 1Password CLI
+alias actions-up='GITHUB_TOKEN=$(op read "op://Personal/GitHub/token") npx actions-up'
+
+# With macOS Keychain
+alias actions-up='GITHUB_TOKEN=$(security find-generic-password -w -s "github-token") npx actions-up'
+```
+
+## Example
+
+```yaml
+# Before
+- uses: actions/checkout@v3
+- uses: actions/setup-node@v3
+
+# After running actions-up
+- uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+```
+
+## Security
+
+Actions Up promotes security best practices:
+
+- **SHA Pinning**: Uses commit SHA instead of mutable tags
+- **Version Comments**: Adds version as comment for readability
+- **No Auto-Updates**: Full control over what gets updated
+
+## Contributing
+
+See [Contributing Guide](https://github.com/azat-io/actions-up/blob/main/contributing.md).
+
+## License
+
+MIT &copy; [Azat S.](https://azat.io)