apify-test-tools 0.10.1-beta.3 → 0.10.1-beta.4

package/.github/workflows/public_platform-tests-claude-investigate-and-fix.yaml

@@ -70,6 +70,9 @@ on:
             TESTER_APIFY_TOKEN_READ_ONLY:
                 required: true
                 description: Apify token used only for read-only investigation — reading the failing run, its log and its storages.
+            NPM_TOKEN:
+                required: false
+                description: Read-only token for installing private npm packages before Claude runs.
 
 jobs:
     investigate:
@@ -166,8 +169,10 @@ jobs:
             id-token: write
             actions: read
         steps:
-            - name: Checkout repository
-              uses: actions/checkout@v5
+            - name: Setup repository and dependencies
+              uses: apify/apify-test-tools/.github/actions/checkout-restore-dependencies@workflows-v0
+              with:
+                  npm-token: ${{ secrets.NPM_TOKEN }}
 
             - name: Run Claude Code
               id: claude

package/CHANGELOG.md

@@ -5,10 +5,16 @@ All notable changes to this project will be documented in this file.
 <!-- git-cliff-unreleased-start -->
 ## 0.10.1 - **not yet released**
 
+### 🚀 Features
+
+- **relative-path:** Path safety and manipulation lib ([#154](https://github.com/apify/apify-test-tools/pull/154)) ([c151a1c](https://github.com/apify/apify-test-tools/commit/c151a1c2755fef98b335d48a3461f5042b90def9)) by [@JuanGalilea](https://github.com/JuanGalilea)
+- **logger:** Add logger and ban console statements ([#170](https://github.com/apify/apify-test-tools/pull/170)) ([b295d36](https://github.com/apify/apify-test-tools/commit/b295d363276c92fc6c30dd34d7a90acef5d380bf)) by [@JuanGalilea](https://github.com/JuanGalilea), closes [#156](https://github.com/apify/apify-test-tools/issues/156)
+
 ### 🐛 Bug Fixes
 
 - **internal-workflows:** Wait out npm&#x27;s async publish before holding the major tag ([#160](https://github.com/apify/apify-test-tools/pull/160)) ([78434f0](https://github.com/apify/apify-test-tools/commit/78434f03d288ecbd383d55d56a1610f06ded298f)) by [@metalwarrior665](https://github.com/metalwarrior665)
 - Skip builds and tests when the net diff is empty ([#171](https://github.com/apify/apify-test-tools/pull/171)) ([874d70c](https://github.com/apify/apify-test-tools/commit/874d70ca5506f7ec742a1808c9bf6c670f08552c)) by [@artogahr](https://github.com/artogahr)
+- **workflows:** Add npm install step to Claude fix workflow ([#161](https://github.com/apify/apify-test-tools/pull/161)) ([d8884e0](https://github.com/apify/apify-test-tools/commit/d8884e07f778de14c8d9d7f0ec9e0a1672c224ad)) by [@foxt451](https://github.com/foxt451), closes [#39](https://github.com/apify/apify-test-tools/issues/39)
 
 
 <!-- git-cliff-unreleased-end -->

package/CONTRIBUTING.md

@@ -14,6 +14,15 @@ The package consists of three parts:
 - `bin/slack.ts` sending notifications to slack
 - `bin/test-report.ts` processing vitest's test reports
 
+CLI command results use `writeJson` from `bin/output.ts` to write newline-terminated JSON to stdout.
+Use the CLI `logger` from `bin/logger.ts` for diagnostics; every level writes to stderr.
+ESLint rejects `console.log` throughout the codebase and all direct `console` calls in `bin/`.
+The importable library in `lib/` keeps its own diagnostics; CLI log levels apply only to `bin/`.
+
+The CLI's global `--log-level` option accepts `debug`, `info` (default), `warn`, `error`, or `silent`.
+It filters diagnostics without affecting command results. Use `logger.debug` for detailed troubleshooting,
+`logger.info` for progress, `logger.warn` for recoverable problems, and `logger.error` for failures.
+
 ## Test library
 
 - `lib/extend-expect.ts` - custom matchers

package/bin/build-from-local.ts

@@ -8,6 +8,7 @@ import { ActorSourceType } from 'apify-client';
 
 import { dryRunBuildData, LOCAL_SOURCE_VERSION_NUMBER, runAndSummarizeBuilds } from './build.js';
 import { buildDockerIgnoreMatcher } from './dockerignore.js';
+import { logger } from './logger.js';
 import { isPathWithinScope } from './path-utils.js';
 import type { ActorConfig, BuildData } from './types.js';
 import type { SourceFile } from './utils.js';
@@ -34,7 +35,7 @@ export const collectSourceFiles = async (actorName: string, actorDir: string): P
     const isMonorepoActor = !!contextAbsDir && isOutsideDir(contextAbsDir, absActorDir);
 
     const dockerContextDirAbs = isMonorepoActor ? contextAbsDir! : absActorDir;
-    const keptFilePaths = collectNonIgnoredFiles(dockerContextDirAbs, repoRoot);
+    const keptFilePaths = await collectNonIgnoredFiles(dockerContextDirAbs, repoRoot);
 
     if (!isMonorepoActor) {
         return Promise.all(keptFilePaths.map(async (filePath) => readSourceFile(filePath, dockerContextDirAbs)));
@@ -64,9 +65,9 @@ export const collectSourceFiles = async (actorName: string, actorDir: string): P
 // regardless of .gitignore/.dockerignore, matching Apify CLI's own behavior. Files matching the
 // hardcoded secret-pattern backstop (keys, certs, .env variants) are dropped unconditionally,
 // .actor/ included, since those should never ship regardless of what the ignore files say.
-export const collectNonIgnoredFiles = (dockerContextDir: string, repoRoot: string): string[] => {
-    const relativePaths = listRepoFilePaths(repoRoot, dockerContextDir);
-    const ignoredPaths = getGitignoredPaths(relativePaths);
+export const collectNonIgnoredFiles = async (dockerContextDir: string, repoRoot: string): Promise<string[]> => {
+    const relativePaths = await listRepoFilePaths(repoRoot, dockerContextDir);
+    const ignoredPaths = await getGitignoredPaths(relativePaths, repoRoot);
     const rootRelativePaths = new Map(
         relativePaths.map((relPath) => [
             relPath,
@@ -104,7 +105,7 @@ export const flattenMonorepoContext = async (
     actorJson: Record<string, unknown>,
     keptContextFiles: string[],
 ): Promise<{ tempDir: string; filePaths: string[] }> => {
-    console.error(`[${actorName}]: monorepo actor detected — flattening from Docker context`);
+    logger.info(`[${actorName}]: monorepo actor detected — flattening from Docker context`);
 
     const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), `apify-build-${actorName.replace('/', '_')}-`));
     const filePaths: string[] = [];
@@ -194,9 +195,9 @@ export const runBuildsFromLocal = async ({
     dryRun: boolean;
 }): Promise<BuildData[]> => {
     if (dryRun) {
-        console.error('[DRY RUN] Would build from local source:');
+        logger.info('[DRY RUN] Would build from local source:');
         for (const { actorFullName, folder } of actorConfigs) {
-            console.error(`  ${actorFullName} (${folder})`);
+            logger.info(`  ${actorFullName} (${folder})`);
         }
         return actorConfigs.map(({ actorFullName }) => dryRunBuildData(actorFullName, LOCAL_SOURCE_VERSION_NUMBER));
     }

package/bin/build.ts

@@ -2,6 +2,7 @@ import type * as ApifyClientTypes from 'apify-client';
 import { ActorSourceType, ApifyClient } from 'apify-client';
 
 import { normalizeRepoUrl } from './git.js';
+import { logger } from './logger.js';
 import type { ActorConfig, BuildData } from './types.js';
 
 type BuildPrActorOptions = {
@@ -28,7 +29,7 @@ const ACTOR_SETUP_REQUIREMENT =
  */
 export const resolveDefaultVersion = (actorFullName: string, actorInfo: ApifyClientTypes.Actor) => {
     const defaultBuildTag = actorInfo.defaultRunOptions.build;
-    console.error(`Default build tag for ${actorFullName} is ${defaultBuildTag}`);
+    logger.info(`Default build tag for ${actorFullName} is ${defaultBuildTag}`);
 
     // We could technically allow this but in most cases this is accidentally set wrongly and there is a workaround
     if (defaultBuildTag.match(/\d+\.\d+\.\d+/)) {
@@ -43,7 +44,7 @@ export const resolveDefaultVersion = (actorFullName: string, actorInfo: ApifyCli
         throw new Error(`[${actorFullName}] No build found for tag "${defaultBuildTag}". ${ACTOR_SETUP_REQUIREMENT}`);
     }
     const defaultVersionNumber = defaultBuildNumber.match(/(\d+\.\d+)\.\d+/)![1];
-    console.error(`Default version for ${actorFullName} is ${defaultVersionNumber}`);
+    logger.info(`Default version for ${actorFullName} is ${defaultVersionNumber}`);
 
     const defaultVersion = actorInfo.versions.find((version) => version.versionNumber === defaultVersionNumber);
 
@@ -139,7 +140,7 @@ export class ApifyBuilder {
         // We also get back actId so the testing actor can both match by actor ID and name
         const { id, actId, buildNumber } = await actorClient.build(versionNumber, { useCache });
 
-        console.error(`[${this.actorFullName}]: ${id} (${buildNumber})`);
+        logger.info(`[${this.actorFullName}]: ${id} (${buildNumber})`);
         return { buildId: id, actorRawId: actId, buildNumber, actorFullName: this.actorFullName };
     };
 
@@ -147,20 +148,20 @@ export class ApifyBuilder {
         const build = await this.apifyClient.build(buildId).waitForFinish();
         const versionNumber = build.buildNumber;
         if (build.status === 'FAILED' || build.status === 'TIMED-OUT') {
-            console.error(`[${this.actorFullName}]: ${versionNumber}`);
+            logger.error(`[${this.actorFullName}]: ${versionNumber}`);
             try {
                 const log = await this.apifyClient.build(buildId).log().get();
                 const logTail = log?.split('\n').slice(-40).join('\n');
-                console.error(`\n--- BUILD LOG (last 40 lines) ---\n${logTail}\n---`);
+                logger.error(`\n--- BUILD LOG (last 40 lines) ---\n${logTail}\n---`);
             } catch (err) {
-                console.error(`[${this.actorFullName}]: Failed to fetch build log: ${err}`);
+                logger.error(`[${this.actorFullName}]: Failed to fetch build log: ${err}`);
             }
             throw new Error(
                 `[BUILD][${this.actorFullName}]: Build ${buildId} (${versionNumber}) failed. ` +
                     `Not continuing with other builds and tests.`,
             );
         }
-        console.error(`[${this.actorFullName}]: ${versionNumber}`);
+        logger.info(`[${this.actorFullName}]: ${versionNumber}`);
         return build;
     };
 
@@ -227,7 +228,7 @@ export class ApifyBuilder {
         type CorrectBuildColletionItem = (typeof items)[0] & { buildNumber: string };
         const buildsToDelete = (items as CorrectBuildColletionItem[]).filter((build) => {
             if (build.buildNumber === defaultBuildNumber) {
-                console.error(
+                logger.info(
                     `[DELETE OLD BUILDS][${this.actorFullName}]: Skipping default build ${defaultBuildNumber} (${defaultBuildTag}). ` +
                         `We never delete default builds`,
                 );
@@ -238,7 +239,7 @@ export class ApifyBuilder {
                 (protectedBuildNumber) => protectedBuildNumber.buildNumber === build.buildNumber,
             );
             if (protectedTagFound) {
-                console.error(
+                logger.info(
                     `[DELETE OLD BUILDS][${this.actorFullName}]: Skipping protected build ${protectedTagFound.buildNumber} (${protectedTagFound.tag}).`,
                 );
                 return false;
@@ -247,7 +248,7 @@ export class ApifyBuilder {
             if (taggedDevelBuildNumber && build.buildNumber === taggedDevelBuildNumber) {
                 const shouldDeleteDevelBuild = build.startedAt.getTime() < daysAgoUnixDevel;
                 if (shouldDeleteDevelBuild) {
-                    console.error(
+                    logger.info(
                         `[DELETE OLD BUILDS][${this.actorFullName}]: Removing olf devel build ${taggedDevelBuildNumber}.`,
                     );
                 }
@@ -256,7 +257,7 @@ export class ApifyBuilder {
             return build.startedAt.getTime() < daysAgoUnixProd;
         });
 
-        console.error(
+        logger.info(
             `[DELETE OLD BUILDS][${this.actorFullName}]: Deleting ${buildsToDelete.length} old builds that are non-default and ` +
                 `older than 30 days from total ${items.length}`,
         );
@@ -271,8 +272,8 @@ export const waitAndSummarizeBuilds = async (
     buildersMap: Map<string, ApifyBuilder>,
     label: string,
 ): Promise<BuildData[]> => {
-    console.error('=========================================');
-    console.error(`FINISHED ${label}:`);
+    logger.info('=========================================');
+    logger.info(`FINISHED ${label}:`);
     await Promise.all(
         startedBuilds.map(async (buildData) => {
             const builder = buildersMap.get(buildData.actorFullName)!;
@@ -280,12 +281,12 @@ export const waitAndSummarizeBuilds = async (
         }),
     );
 
-    console.error('=========================================');
-    console.error('SUMMARY:');
+    logger.info('=========================================');
+    logger.info('SUMMARY:');
     for (const buildData of startedBuilds.sort((a, b) => a.actorFullName.localeCompare(b.actorFullName))) {
-        console.error(`[${buildData.actorFullName}]: ${buildData.buildNumber}`);
+        logger.info(`[${buildData.actorFullName}]: ${buildData.buildNumber}`);
     }
-    console.error('=========================================');
+    logger.info('=========================================');
 
     return startedBuilds;
 };
@@ -298,8 +299,8 @@ export const runAndSummarizeBuilds = async (
     const buildersByActorFullName = new Map<string, ApifyBuilder>(
         actorConfigs.map((actorConfig) => [actorConfig.actorFullName, ApifyBuilder.fromActorConfig(actorConfig)]),
     );
-    console.error('=========================================');
-    console.error(`STARTED ${label}:`);
+    logger.info('=========================================');
+    logger.info(`STARTED ${label}:`);
     const startedBuilds = await Promise.all(
         actorConfigs.map(async (actorConfig) =>
             buildOneActor(actorConfig, buildersByActorFullName.get(actorConfig.actorFullName)!),
@@ -366,9 +367,9 @@ export const runBuilds = async ({
     );
 
     if (dryRun) {
-        console.error('[DRY RUN] Would build:');
+        logger.info('[DRY RUN] Would build:');
         for (const { actorConfig, versionNumber } of buildConfigs) {
-            console.error(`  ${actorConfig.actorFullName} (${versionNumber})`);
+            logger.info(`  ${actorConfig.actorFullName} (${versionNumber})`);
         }
         return buildConfigs.map(({ actorConfig, versionNumber }) =>
             dryRunBuildData(actorConfig.actorFullName, versionNumber),

package/bin/diff-changes.ts

@@ -1,5 +1,6 @@
 import { isCosmeticOnlyJsonSchemaChange } from './diff-json-schema.js';
 import { type DockerIgnoreMatcher, loadDockerIgnore } from './dockerignore.js';
+import { logger } from './logger.js';
 import { findContainingScope, hoistPath, isPathWithinScope } from './path-utils.js';
 import type { ActorConfig, Commit } from './types.js';
 
@@ -44,12 +45,12 @@ type FileChangeForActor =
  * 6. .json inside the actor's own `.actor/` dir with only cosmetic schema diffs → cosmetic (semantically verified)
  * 7. Everything else → functional
  */
-const classifyFileChange = (
+const classifyFileChange = async (
     originalFilePath: string,
     actorConfig: ActorConfig,
     commits: Commit[],
     dockerIgnoreMatcher: DockerIgnoreMatcher,
-): FileChangeForActor => {
+): Promise<FileChangeForActor> => {
     const lowercaseFilePath = originalFilePath.toLowerCase();
 
     // TODO: hardcodes that there's a single repo-wide changelog belonging to every actor. Should instead
@@ -89,7 +90,7 @@ const classifyFileChange = (
     }
 
     if (lowercaseFilePath.endsWith('.json') && isUnderActorDotDir) {
-        const isCosmetic = isCosmeticOnlyJsonSchemaChange(commits, originalFilePath);
+        const isCosmetic = await isCosmeticOnlyJsonSchemaChange(commits, originalFilePath);
         if (isCosmetic) {
             return { impact: 'cosmetic', semanticallyVerified: true };
         }
@@ -159,19 +160,19 @@ const groupFilesByActorSet = (fileToActors: Map<string, Set<string>>): ChangeGro
 const logChangeGroups = (groups: ChangeGroup[]): void => {
     for (const { actors, files } of groups) {
         if (actors.length > 1) {
-            console.error(`[DIFF]: Shared changes for actors ${actors.join(', ')}: ${files.join(', ')}`);
+            logger.info(`[DIFF]: Shared changes for actors ${actors.join(', ')}: ${files.join(', ')}`);
         } else {
-            console.error(`[DIFF]: Changes specific to actor ${actors[0]}: ${files.join(', ')}`);
+            logger.info(`[DIFF]: Changes specific to actor ${actors[0]}: ${files.join(', ')}`);
         }
     }
 };
 
-export const getChangedActors = ({
+export const getChangedActors = async ({
     filepathsChanged,
     actorConfigs,
     isLatest = false,
     commits,
-}: ShouldBuildAndTestOptions): ActorConfig[] => {
+}: ShouldBuildAndTestOptions): Promise<ActorConfig[]> => {
     const actorsChangedMap = new Map<string, ActorChangeEntry>();
 
     for (const actorConfig of actorConfigs) {
@@ -184,7 +185,7 @@ export const getChangedActors = ({
                 continue;
             }
 
-            const change = classifyFileChange(originalFilePath, actorConfig, commits, dockerIgnoreMatcher);
+            const change = await classifyFileChange(originalFilePath, actorConfig, commits, dockerIgnoreMatcher);
 
             if (change.impact === 'ignored' || change.impact === 'outside-context') continue;
             if (change.impact === 'cosmetic' && !isLatest) continue;
@@ -205,9 +206,9 @@ export const getChangedActors = ({
 
     if (actorsChanged.length > 0) {
         const actors = actorsChanged.map((config) => config.actorFullName);
-        console.error(`[DIFF]: Actors to be built and tested: ${actors.join(', ')}`);
+        logger.info(`[DIFF]: Actors to be built and tested: ${actors.join(', ')}`);
     } else {
-        console.error(`[DIFF]: No relevant files changed, skipping builds and tests`);
+        logger.info(`[DIFF]: No relevant files changed, skipping builds and tests`);
     }
 
     return actorsChanged;

package/bin/diff-json-schema.ts

@@ -1,5 +1,6 @@
+import { logger } from './logger.js';
 import type { Commit } from './types.js';
-import { spawnCommand } from './utils.js';
+import { runGitCommand } from './utils.js';
 
 const COSMETIC_JSON_FIELD_NAMES = new Set([
     'title',
@@ -28,21 +29,22 @@ const isCosmeticObjectChange = (oldVal: unknown, newVal: unknown, currentKey?: s
  * Returns true if the two JSON strings differ only in cosmetic fields
  * (title, description, example, enumTitles, sectionCaption, sectionDescription).
  */
-export const isCosmeticOnlyJsonSchemaChange = (commits: Commit[], changedFilepath: string): boolean => {
+export const isCosmeticOnlyJsonSchemaChange = async (commits: Commit[], changedFilepath: string): Promise<boolean> => {
     // TODO: validate this is the right commit range
     const oldRef = `${commits[0].sha}~`;
     const newRef = commits[commits.length - 1].sha;
-    let oldJson: unknown;
-    let newJson: unknown;
-    try {
-        const oldContent = spawnCommand(`git show ${oldRef}:${changedFilepath}`);
-        const newContent = spawnCommand(`git show ${newRef}:${changedFilepath}`);
 
-        oldJson = JSON.parse(oldContent);
-        newJson = JSON.parse(newContent);
-    } catch {
-        console.error(
-            `Failed to get or parse JSON content for ${changedFilepath} at refs ${oldRef} and ${newRef}, maybe it is new file or deleted? Treating it as a non-cosmetic change.`,
+    const [oldJson, newJson] = await Promise.all([
+        runGitCommand(['show', `${oldRef}:${changedFilepath}`])
+            .then(JSON.parse)
+            .catch(() => undefined),
+        runGitCommand(['show', `${newRef}:${changedFilepath}`])
+            .then(JSON.parse)
+            .catch(() => undefined),
+    ]);
+    if (!oldJson || !newJson) {
+        logger.info(
+            `Failed to get JSON content for ${changedFilepath} at refs ${oldRef} and ${newRef}, maybe it is new file or deleted? Treating it as a non-cosmetic change.`,
         );
         return false;
     }

package/bin/git.ts

@@ -1,5 +1,6 @@
+import { logger } from './logger.js';
 import type { Commit, Config } from './types.js';
-import { spawnCommand } from './utils.js';
+import { GitCommandError, runGitCommand } from './utils.js';
 
 export const GIT_FORMAT_SEPARATOR = '»¦«';
 const GIT_LOG_FORMAT = ['%H', '%aN<%aE>', '%aD', '%s'].join(GIT_FORMAT_SEPARATOR);
@@ -7,19 +8,20 @@ const GIT_LOG_FORMAT = ['%H', '%aN<%aE>', '%aD', '%s'].join(GIT_FORMAT_SEPARATOR
 /**
  * Gets the list of changed files between the given commits (inclusive).
  */
-export const getChangedFiles = (commits: Commit[]) => {
+export const getChangedFiles = async (commits: Commit[]) => {
     // getCommits never returns an empty list (the rerun check returns all commits when the base commit
     // is the branch HEAD, and an empty git range throws when parsing), so this signals a programmer error
     if (commits.length === 0) {
         throw new Error('Cannot get changed files: the commit list is empty. This should never happen.');
     }
 
-    const changedFilesString = spawnCommand(
-        `git diff --name-only ${commits[0].sha}~..${commits[commits.length - 1].sha}`,
+    const changedFilesString = await runGitCommand(
+        ['diff', '--name-only', `${commits[0].sha}~..${commits[commits.length - 1].sha}`],
+        { operation: 'get the list of changed files between commits' },
     );
 
     const changedFiles = changedFilesString.split('\n').filter(Boolean);
-    console.error(`Changed files (up to 50): ${changedFiles.slice(0, 50).join(', ')}`);
+    logger.info(`Changed files (up to 50): ${changedFiles.slice(0, 50).join(', ')}`);
     return changedFiles;
 };
 
@@ -28,17 +30,36 @@ export const getChangedFiles = (commits: Commit[]) => {
  * (i.e. a genuine "merge from target" commit, not a merge of some unrelated branch).
  * Uses the full targetBranch..sourceBranch range, ignoring baseCommit.
  */
-export const hasMergeFromTarget = (sourceBranch: string, targetBranch: string): boolean => {
-    const mergeShas = spawnCommand(`git log --merges --pretty=format:%H ${targetBranch}..${sourceBranch}`)
+export const hasMergeFromTarget = async (sourceBranch: string, targetBranch: string): Promise<boolean> => {
+    const mergeShas = (
+        await runGitCommand(['log', '--merges', '--pretty=format:%H', `${targetBranch}..${sourceBranch}`], {
+            operation: 'find merge commits on the source branch that are absent from the target branch',
+        })
+    )
         .split('\n')
         .filter(Boolean);
 
     for (const sha of mergeShas) {
-        const parents = spawnCommand(`git log -1 --pretty=format:%P ${sha}`).trim().split(' ');
+        const parents = (
+            await runGitCommand(['log', '-1', '--pretty=format:%P', sha], {
+                operation: 'get parents of a merge commit',
+            })
+        ).split(' ');
         for (const parent of parents) {
             // git merge-base A B outputs the common ancestor.
             // If that equals A, then A is an ancestor of B (i.e. parent is reachable from targetBranch).
-            const mergeBase = spawnCommand(`git merge-base ${parent} ${targetBranch}`);
+            let mergeBase: string;
+            try {
+                mergeBase = await runGitCommand(['merge-base', parent, targetBranch], {
+                    operation: 'check whether a merge parent is reachable from the target branch',
+                });
+            } catch (error) {
+                // Exit code 1 on merge-base means the histories have no common ancestor.
+                if (error instanceof GitCommandError && error.exitCode === 1) {
+                    continue;
+                }
+                throw error;
+            }
             if (mergeBase === parent) {
                 return true;
             }
@@ -51,8 +72,11 @@ export const hasMergeFromTarget = (sourceBranch: string, targetBranch: string):
  * Returns all files touched by non-merge commits on the branch (full history, ignoring baseCommit).
  * Used to check whether the branch itself has any functional changes, independent of what master merged in.
  */
-export const getBranchOnlyChangedFiles = (sourceBranch: string, targetBranch: string): string[] => {
-    const output = spawnCommand(`git log --no-merges --name-only --pretty=format: ${targetBranch}..${sourceBranch}`);
+export const getBranchOnlyChangedFiles = async (sourceBranch: string, targetBranch: string): Promise<string[]> => {
+    const output = await runGitCommand(
+        ['log', '--no-merges', '--name-only', '--pretty=format:', `${targetBranch}..${sourceBranch}`],
+        { operation: 'list files changed by non-merge commits on the source branch' },
+    );
     return output.split('\n').filter(Boolean);
 };
 
@@ -79,10 +103,12 @@ export const parseBaseCommit = (shaOrCommit: string | undefined): string | undef
     return sha;
 };
 
-const fetchAllBranchCommits = (sourceBranch: string, targetBranch: string): Commit[] => {
-    const commitsStrings = spawnCommand(
-        `git log --pretty=format:'${GIT_LOG_FORMAT}' ${targetBranch}..${sourceBranch}`,
-    ).split('\n');
+const fetchAllBranchCommits = async (sourceBranch: string, targetBranch: string): Promise<Commit[]> => {
+    const output = await runGitCommand(
+        ['log', `--pretty=format:${GIT_LOG_FORMAT}`, `${targetBranch}..${sourceBranch}`],
+        { operation: 'list commits reachable from the source ref but absent from the target ref' },
+    );
+    const commitsStrings = output.split('\n');
     const commits = commitsStrings.map((commitString) => parseCommit(commitString));
     commits.reverse();
     return commits;
@@ -92,22 +118,22 @@ const fetchAllBranchCommits = (sourceBranch: string, targetBranch: string): Comm
  * Gets the commits between sourceBranch and targetBranch (exclusive).
  * - If baseCommit is provided, only returns commits after the baseCommit.
  */
-export const getCommits = ({
+export const getCommits = async ({
     sourceBranch,
     targetBranch,
     baseCommit,
-}: Pick<Config, 'sourceBranch' | 'targetBranch' | 'baseCommit'>): Commit[] => {
+}: Pick<Config, 'sourceBranch' | 'targetBranch' | 'baseCommit'>): Promise<Commit[]> => {
     const baseCommitSha = parseBaseCommit(baseCommit);
-    const commits = fetchAllBranchCommits(sourceBranch, targetBranch);
+    const commits = await fetchAllBranchCommits(sourceBranch, targetBranch);
 
     // The last validated (base) commit being the branch HEAD means nothing new was pushed since the last
     // validation — the dev reran the workflow (or force-pushed to the same state) to trigger a clean test
     const headSha = commits[commits.length - 1]?.sha;
     if (baseCommitSha !== undefined && baseCommitSha === headSha) {
-        console.error(
+        logger.info(
             `Detected rerun with the same commit that we already validated. This usually means the user wants to rerun the Action from scratch, ignoring last validated commit ${baseCommitSha} and returning all commits`,
         );
-        console.error(`Commits being returned: ${commits.map((c) => c.sha).join(', ')}`);
+        logger.info(`Commits being returned: ${commits.map((c) => c.sha).join(', ')}`);
         return commits;
     }
 
@@ -116,17 +142,15 @@ export const getCommits = ({
     const hasBaseCommit = baseCommitIndex !== -1;
     if (hasBaseCommit) {
         const commitsUpToBaseCommit = commits.slice(baseCommitIndex + 1);
-        console.error(
+        logger.info(
             `Found base commit ${baseCommitSha} at index ${baseCommitIndex}, returning ${commitsUpToBaseCommit.length} commits after it`,
         );
-        console.error(`Commits being returned: ${commitsUpToBaseCommit.map((c) => c.sha).join(', ')}`);
+        logger.info(`Commits being returned: ${commitsUpToBaseCommit.map((c) => c.sha).join(', ')}`);
         return commitsUpToBaseCommit;
     }
 
-    console.error(
-        `Base commit ${baseCommitSha} not found in the commit range, returning all ${commits.length} commits`,
-    );
-    console.error(`Commits being returned: ${commits.map((c) => c.sha).join(', ')}`);
+    logger.info(`Base commit ${baseCommitSha} not found in the commit range, returning all ${commits.length} commits`);
+    logger.info(`Commits being returned: ${commits.map((c) => c.sha).join(', ')}`);
     return commits;
 };
 
@@ -148,8 +172,10 @@ export const parseCommit = (commitString: string): Commit => {
  * Returns the currently checked-out branch. Release builds point the Actor version at this branch,
  * so a detached HEAD (no branch to point at) is an error rather than a guess.
  */
-export const getCurrentBranch = (): string => {
-    const branch = spawnCommand('git rev-parse --abbrev-ref HEAD');
+export const getCurrentBranch = async (): Promise<string> => {
+    const branch = await runGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], {
+        operation: 'determine the current branch for release',
+    });
     if (branch === 'HEAD') {
         throw new Error(
             'Cannot determine the branch to release: HEAD is detached. Check out the branch you want to release.',
@@ -162,8 +188,11 @@ export const getCurrentBranch = (): string => {
  * Reads the repository URL from the `origin` remote, rewritten to the SSH form the Apify platform
  * uses for Git repo sources, e.g. git@github.com:apify-store/google-maps
  */
-const getOriginRepoUrl = (): string => {
-    return spawnCommand('git remote get-url origin').replace(/^https:\/\/github\.com\//, 'git@github.com:');
+const getOriginRepoUrl = async (): Promise<string> => {
+    const rawUrl = await runGitCommand(['remote', 'get-url', 'origin'], {
+        operation: 'read the origin repository URL',
+    });
+    return rawUrl.replace(/^https:\/\/github\.com\//, 'git@github.com:');
 };
 
 /**
@@ -171,8 +200,8 @@ const getOriginRepoUrl = (): string => {
  * each Actor's default version, so a fork or mirror remote can't repoint a published Actor. An explicit
  * --repo-url skips that check: passing it is how you move an Actor to another repository on purpose.
  */
-export const resolveRepoUrl = (explicitRepoUrl: string | undefined) => ({
-    repoUrl: explicitRepoUrl ?? getOriginRepoUrl(),
+export const resolveRepoUrl = async (explicitRepoUrl: string | undefined) => ({
+    repoUrl: explicitRepoUrl ?? (await getOriginRepoUrl()),
     shouldVerifyRepoUrl: explicitRepoUrl === undefined,
 });
 
@@ -207,7 +236,7 @@ const ZERO_SHA_REGEX = /^0{40}$/;
  * Unlike the PR path (getCommits), there is no lenient fallback. Falling back to "everything"
  * would rebuild the latest build of every Actor and post it to Slack, so every problem is an error.
  */
-export const resolveReleaseBaseCommit = (baseCommit: string): string => {
+export const resolveReleaseBaseCommit = async (baseCommit: string): Promise<string> => {
     const sha = parseBaseCommit(baseCommit);
     if (!sha) {
         throw new Error('--base-commit is required for release. See the README section "Releasing Actors".');
@@ -218,15 +247,27 @@ export const resolveReleaseBaseCommit = (baseCommit: string): string => {
                 `Rerun with --base-commit set to the last commit before the changes you want to release.`,
         );
     }
-    // --quiet makes rev-parse print nothing (instead of an error) when the commit is missing
-    if (!spawnCommand(`git rev-parse --verify --quiet "${sha}^{commit}"`)) {
+    // --quiet suppresses Git's error text for a missing commit, but Git still exits with code 1.
+    const verifiedSha = await runGitCommand(['rev-parse', '--verify', '--quiet', `${sha}^{commit}`], {
+        operation: 'verify the release base commit in local Git history',
+    }).catch((error: unknown) => {
+        if (error instanceof GitCommandError && error.exitCode === 1) return '';
+        throw error;
+    });
+    if (!verifiedSha) {
         throw new Error(
             `Base commit ${sha} is not in the local git history. Either the checkout is shallow ` +
                 `(fetch the full history, e.g. fetch-depth: 0 in actions/checkout) or the branch was force-pushed.`,
         );
     }
     // git merge-base A B outputs the common ancestor. If that equals A, then A is an ancestor of B.
-    if (spawnCommand(`git merge-base ${sha} HEAD`) !== sha) {
+    const mergeBase = await runGitCommand(['merge-base', verifiedSha, 'HEAD'], {
+        operation: 'check whether the release base commit is an ancestor of HEAD',
+    }).catch((error: unknown) => {
+        if (error instanceof GitCommandError && error.exitCode === 1) return '';
+        throw error;
+    });
+    if (mergeBase !== sha) {
         throw new Error(
             `Base commit ${sha} is not an ancestor of HEAD, most likely because the branch was force-pushed. ` +
                 `The changed files cannot be determined reliably. Rerun with --base-commit set to an ancestor of HEAD ` +
@@ -239,11 +280,13 @@ export const resolveReleaseBaseCommit = (baseCommit: string): string => {
 const CHANGELOG_PATH = 'CHANGELOG.md';
 
 /** Returns the lines added to the root CHANGELOG.md between baseSha and HEAD, or null if it didn't change. */
-const getChangelogAdditions = (baseSha: string, changedFiles: string[]): string | null => {
+const getChangelogAdditions = async (baseSha: string, changedFiles: string[]): Promise<string | null> => {
     if (!changedFiles.includes(CHANGELOG_PATH)) {
         return null;
     }
-    const diff = spawnCommand('git', ['diff', baseSha, 'HEAD', '--', CHANGELOG_PATH]);
+    const diff = await runGitCommand(['diff', baseSha, 'HEAD', '--', CHANGELOG_PATH], {
+        operation: 'read changelog changes since the last release',
+    });
 
     const added: string[] = [];
     let startedChangelog = false;
@@ -271,12 +314,16 @@ const getChangelogAdditions = (baseSha: string, changedFiles: string[]): string
  * list: with a merge commit, the oldest commit of the merged branch can be older than baseSha, and
  * diffing from its parent would pull in already-released changes.
  */
-export const getReleaseChanges = (baseSha: string) => {
-    if (spawnCommand('git rev-parse HEAD') === baseSha) {
+export const getReleaseChanges = async (baseSha: string) => {
+    if (
+        (await runGitCommand(['rev-parse', 'HEAD'], { operation: 'identify the current release commit' })) === baseSha
+    ) {
         return null;
     }
-    const commits = fetchAllBranchCommits('HEAD', baseSha);
-    const changedFiles = spawnCommand(`git diff --name-only ${baseSha} HEAD`).split('\n').filter(Boolean);
-    const changelog = getChangelogAdditions(baseSha, changedFiles);
+    const commits = await fetchAllBranchCommits('HEAD', baseSha);
+    const changedFiles = await runGitCommand(['diff', '--name-only', baseSha, 'HEAD'], {
+        operation: 'list files changed since the last release',
+    }).then((output) => output.split('\n').filter(Boolean));
+    const changelog = await getChangelogAdditions(baseSha, changedFiles);
     return { commits, changedFiles, changelog };
 };