Utility Functions

/**
 * Resolves the directory in which to use a CLI command
 * @param dir - The directory specified by the user (can be relative or absolute)
 * @param checkExisting - Checks if the directory exists. If true and directory is non-existent, it will fall back to the current working directory
 * @returns Resolved absolute directory path
 */
function resolveWorkingDir(dir: string, checkExisting?: boolean): string;

import { resolveWorkingDir } from "@electron-forge/cli/dist/util/resolve-working-dir";

// Resolve relative path
const resolved = resolveWorkingDir("./my-project");

// Resolve with existence check
const resolvedChecked = resolveWorkingDir("./my-project", true);

// Falls back to current directory if path doesn't exist
const fallback = resolveWorkingDir("/nonexistent/path", true);

/**
 * System validation context for pre-flight checks
 */
interface SystemCheckContext {
  /** The command being executed */
  command: string;
  /** Whether git validation is required */
  git: boolean;
  /** Whether Node.js validation is required */
  node: boolean;
  /** Whether package manager validation is required */
  packageManager: boolean;
}

/**
 * Validates system requirements before command execution
 * @param callerTask - Listr task for progress reporting and sub-task management
 * @returns Promise resolving to validation result or true if checks are skipped
 */
function checkSystem(callerTask: ForgeListrTask<SystemCheckContext>): Promise<any>;

/**
 * Validates package manager version compatibility
 * @returns Promise resolving to package manager name and version string
 * @throws Error if package manager is incompatible
 */
function checkPackageManager(): Promise<string>;

/**
 * Retrieves git version from system
 * @returns Promise resolving to git version string or null if not found
 */
function getGitVersion(): Promise<string | null>;

/**
 * Validates pnpm configuration for Electron Forge compatibility
 * @throws Error if pnpm configuration is incompatible
 */
function checkPnpmConfig(): Promise<void>;

/**
 * Supported package manager version ranges
 */
interface PackageManagerVersions {
  npm: {
    all: "^3.0.0 || ^4.0.0 || ~5.1.0 || ~5.2.0 || >= 5.4.2";
    darwin: ">= 5.4.0";
    linux: ">= 5.4.0";
  };
  yarn: {
    all: ">= 1.0.0";
  };
  pnpm: {
    all: ">= 8.0.0";
  };
}

/**
 * Process event handlers for error management
 * - Handles unhandledRejection events
 * - Handles uncaughtException events
 * - Provides formatted error output
 * - Exits process with code 1 on errors
 */
interface ErrorHandling {
  /** Handles unhandled promise rejections */
  onUnhandledRejection: (reason: string, promise: Promise<unknown>) => void;
  /** Handles uncaught exceptions */
  onUncaughtException: (err: Error) => void;
}

// System validation in custom workflow
import { checkSystem, checkPackageManager, SystemCheckContext } from "@electron-forge/cli/dist/util/check-system";
import { resolveWorkingDir } from "@electron-forge/cli/dist/util/resolve-working-dir";

// Validate package manager
try {
  const pmInfo = await checkPackageManager();
  console.log(`Using ${pmInfo}`); // Outputs: "npm@8.5.0" or similar
} catch (error) {
  console.error("Package manager validation failed:", error.message);
}

// Directory resolution with fallback
const projectDir = resolveWorkingDir(process.argv[2] || ".", true);
console.log(`Working in: ${projectDir}`);

// Skip system check example
const skipFile = require('path').resolve(require('os').homedir(), '.skip-forge-system-check');
if (require('fs').existsSync(skipFile)) {
  console.log('System checks will be skipped for ~800ms performance improvement');
}

/**
 * Listr task interface for system checks
 */
interface ForgeListrTask<T> {
  title: string;
  newListr<U>(tasks: any[], options?: any): any;
}

/**
 * Supported package manager types
 */
type SupportedPackageManager = 'npm' | 'yarn' | 'pnpm';