@fredlackey/devutils 0.0.1 → 0.0.3

package/src/installs/xcode.js

@@ -1,44 +1,560 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Install Xcode Command Line Tools.
+ * @fileoverview Install Xcode (Full IDE) on macOS.
  * @module installs/xcode
+ *
+ * Xcode is Apple's integrated development environment (IDE) for developing software
+ * for all Apple platforms: iOS, iPadOS, macOS, watchOS, tvOS, and visionOS.
+ *
+ * This installer uses the `xcodes` CLI tool to download and install Xcode from
+ * Apple's servers. The xcodes tool provides version management and faster downloads
+ * (via aria2) compared to the Mac App Store.
+ *
+ * IMPORTANT PLATFORM LIMITATION:
+ * Xcode is an Apple-exclusive product and ONLY runs on macOS. There is no legitimate
+ * way to install or run Xcode on Windows, Linux, or other operating systems. Apple
+ * does not support virtualization of macOS on non-Apple hardware.
+ *
+ * What this installer provides:
+ * - Installation of the full Xcode IDE (~40+ GB)
+ * - Swift and Objective-C compilers
+ * - Interface Builder, Instruments, and other development tools
+ * - Simulators for all Apple platforms
+ * - SDKs for iOS, macOS, watchOS, tvOS, and visionOS
+ *
+ * IMPORTANT: This is for the FULL Xcode IDE. For the lightweight Command Line Tools
+ * only (~2.5 GB), use `dev install xcode-clt` instead.
+ *
+ * Prerequisites:
+ * - macOS version compatible with target Xcode version
+ * - Apple ID for downloading from Apple servers
+ * - At least 50 GB free disk space
+ * - Homebrew package manager
  */
 
 const os = require('../utils/common/os');
+const shell = require('../utils/common/shell');
+const brew = require('../utils/macos/brew');
+const fs = require('fs');
+
+/**
+ * Whether this installer requires a desktop environment to function.
+ * Xcode is a GUI integrated development environment (IDE).
+ */
+const REQUIRES_DESKTOP = true;
+
+/**
+ * The path where Xcode is typically installed on macOS.
+ * The standard location is /Applications/Xcode.app.
+ */
+const XCODE_APP_PATH = '/Applications/Xcode.app';
+
+/**
+ * The path to the Xcode developer directory within the app bundle.
+ * This path is used by xcode-select to point to the active developer tools.
+ */
+const XCODE_DEVELOPER_PATH = '/Applications/Xcode.app/Contents/Developer';
+
+/**
+ * The Homebrew formula name for the xcodes CLI tool.
+ * xcodes is a third-party tool that manages Xcode installations.
+ */
+const XCODES_FORMULA = 'xcodesorg/made/xcodes';
+
+/**
+ * The Homebrew formula name for aria2 download accelerator.
+ * aria2 enables 3-5x faster Xcode downloads via parallel connections.
+ */
+const ARIA2_FORMULA = 'aria2';
+
+/**
+ * Check if the full Xcode IDE is installed on macOS.
+ *
+ * This function verifies Xcode installation by:
+ * 1. Checking if Xcode.app exists in /Applications
+ * 2. Verifying the app bundle structure contains expected binaries
+ *
+ * Note: This checks for the full Xcode IDE, not just Command Line Tools.
+ * The presence of /Library/Developer/CommandLineTools is NOT sufficient.
+ *
+ * @returns {boolean} True if full Xcode IDE is installed, false otherwise
+ */
+function isXcodeInstalled() {
+  // Check if the Xcode.app bundle exists
+  if (!fs.existsSync(XCODE_APP_PATH)) {
+    return false;
+  }
+
+  // Verify the developer directory exists within the app bundle
+  // This ensures it's a complete Xcode installation, not a stub
+  if (!fs.existsSync(XCODE_DEVELOPER_PATH)) {
+    return false;
+  }
+
+  // Verify a core Xcode binary exists (xcodebuild)
+  const xcodebuildPath = `${XCODE_DEVELOPER_PATH}/usr/bin/xcodebuild`;
+  return fs.existsSync(xcodebuildPath);
+}
+
+/**
+ * Get the installed Xcode version using xcodebuild command.
+ *
+ * Executes `xcodebuild -version` to retrieve version information.
+ * Output format is typically:
+ *   Xcode 16.2
+ *   Build version 16C5032a
+ *
+ * @returns {Promise<string|null>} The Xcode version string (e.g., "16.2"), or null if not installed
+ */
+async function getXcodeVersion() {
+  // Check if xcodebuild command exists and Xcode is properly configured
+  const result = await shell.exec('xcodebuild -version 2>/dev/null');
+
+  if (result.code !== 0 || !result.stdout) {
+    return null;
+  }
+
+  // Parse the version from the output
+  // Expected format: "Xcode 16.2\nBuild version 16C5032a"
+  const versionMatch = result.stdout.match(/Xcode\s+(\d+\.?\d*\.?\d*)/);
+  if (versionMatch) {
+    return versionMatch[1];
+  }
+
+  return null;
+}
+
+/**
+ * Check if the xcodes CLI tool is installed.
+ *
+ * xcodes is a command-line tool for managing Xcode installations.
+ * It provides faster downloads and version management compared to
+ * the Mac App Store.
+ *
+ * @returns {boolean} True if xcodes is available, false otherwise
+ */
+function isXcodesInstalled() {
+  return shell.commandExists('xcodes');
+}
+
+/**
+ * Install the xcodes CLI tool and aria2 download accelerator via Homebrew.
+ *
+ * This function installs:
+ * - xcodes: CLI tool for downloading and managing Xcode versions
+ * - aria2: Download accelerator for 3-5x faster Xcode downloads
+ *
+ * @returns {Promise<void>}
+ * @throws {Error} If Homebrew is not installed or installation fails
+ */
+async function installXcodesTools() {
+  // Verify Homebrew is available before attempting installation
+  if (!brew.isInstalled()) {
+    throw new Error(
+      'Homebrew is not installed. Please install Homebrew first using:\n' +
+      '  dev install homebrew\n' +
+      'Then retry installing Xcode.'
+    );
+  }
+
+  console.log('Installing xcodes CLI tool and aria2 download accelerator...');
+
+  // First, tap the xcodes repository
+  // This adds the third-party repository containing the xcodes formula
+  const tapResult = await brew.tap('xcodesorg/made');
+  if (!tapResult.success) {
+    throw new Error(
+      `Failed to add xcodes tap.\n` +
+      `Output: ${tapResult.output}\n\n` +
+      `Try running manually: brew tap xcodesorg/made`
+    );
+  }
+
+  // Install xcodes CLI tool
+  console.log('Installing xcodes CLI tool...');
+  const xcodesResult = await brew.install('xcodes');
+  if (!xcodesResult.success) {
+    throw new Error(
+      `Failed to install xcodes.\n` +
+      `Output: ${xcodesResult.output}\n\n` +
+      `Try running manually: brew install xcodesorg/made/xcodes`
+    );
+  }
+
+  // Install aria2 for faster downloads (optional but recommended)
+  console.log('Installing aria2 download accelerator...');
+  const aria2Result = await brew.install(ARIA2_FORMULA);
+  if (!aria2Result.success) {
+    // aria2 failure is not critical, just warn
+    console.log('Warning: Could not install aria2. Downloads will be slower.');
+    console.log('You can install it manually later: brew install aria2');
+  } else {
+    console.log('aria2 installed - Xcode downloads will use parallel connections.');
+  }
+
+  // Verify xcodes installation
+  if (!isXcodesInstalled()) {
+    throw new Error(
+      'xcodes installation appeared to succeed but the command is not available.\n\n' +
+      'Try restarting your terminal and running:\n' +
+      '  which xcodes\n' +
+      '  xcodes version'
+    );
+  }
+
+  console.log('xcodes CLI tool installed successfully.');
+}
+
+/**
+ * Install the full Xcode IDE on macOS using xcodes.
+ *
+ * Prerequisites:
+ * - macOS version compatible with target Xcode version
+ * - Homebrew package manager installed
+ * - Apple ID credentials (environment variables or interactive prompt)
+ * - At least 50 GB free disk space
+ *
+ * Installation process:
+ * 1. Check if Xcode is already installed (idempotency)
+ * 2. Install xcodes and aria2 if not present
+ * 3. Download and install the latest Xcode via xcodes
+ * 4. Accept the Xcode license agreement
+ * 5. Run first-launch setup to install additional components
+ * 6. Verify the installation succeeded
+ *
+ * NOTE: This function will require Apple ID credentials. If XCODES_USERNAME
+ * and XCODES_PASSWORD environment variables are not set, xcodes will prompt
+ * interactively (and optionally save credentials to Keychain).
+ *
+ * @returns {Promise<void>}
+ * @throws {Error} If installation fails
+ */
+async function install_macos() {
+  console.log('Checking if Xcode is already installed...');
+
+  // Check if Xcode is already installed - this ensures idempotency
+  if (isXcodeInstalled()) {
+    const version = await getXcodeVersion();
+    if (version) {
+      console.log(`Xcode ${version} is already installed, skipping...`);
+    } else {
+      console.log('Xcode is already installed, skipping...');
+    }
+    return;
+  }
+
+  console.log('Xcode is not installed. Starting installation...');
+  console.log('');
+  console.log('This will install:');
+  console.log('  - Full Xcode IDE (~40+ GB)');
+  console.log('  - Swift and Objective-C compilers');
+  console.log('  - Interface Builder and Instruments');
+  console.log('  - iOS, macOS, watchOS, tvOS, and visionOS SDKs');
+  console.log('  - Simulators for all Apple platforms');
+  console.log('');
+  console.log('IMPORTANT: You will need an Apple ID to download Xcode.');
+  console.log('');
+
+  // Install xcodes CLI tool if not already present
+  if (!isXcodesInstalled()) {
+    await installXcodesTools();
+  } else {
+    console.log('xcodes CLI tool is already installed.');
+  }
+
+  console.log('');
+  console.log('Downloading and installing the latest Xcode...');
+  console.log('This may take 30-60 minutes depending on your internet connection.');
+  console.log('');
+
+  // Check for Apple ID credentials in environment variables
+  const hasCredentials = process.env.XCODES_USERNAME && process.env.XCODES_PASSWORD;
+  if (!hasCredentials) {
+    console.log('NOTE: Apple ID credentials not found in environment variables.');
+    console.log('You will be prompted to enter your Apple ID and password.');
+    console.log('Credentials will be saved to your macOS Keychain for future use.');
+    console.log('');
+    console.log('To set credentials non-interactively:');
+    console.log('  export XCODES_USERNAME="your-apple-id@example.com"');
+    console.log('  export XCODES_PASSWORD="your-password-or-app-specific-password"');
+    console.log('');
+  }
+
+  // Install the latest Xcode using xcodes
+  // The --latest flag installs the most recent stable release
+  // This command may prompt for Apple ID credentials if not set
+  const installResult = await shell.exec('xcodes install --latest', {
+    timeout: 3600000 // 60 minute timeout for large download
+  });
+
+  // Check if installation succeeded
+  // Note: xcodes may output to stderr for progress, so we check the exit code
+  if (installResult.code !== 0) {
+    // Check if Xcode was actually installed despite the error code
+    // (some warnings may cause non-zero exit but installation succeeds)
+    if (isXcodeInstalled()) {
+      console.log('');
+      console.log('Installation completed with warnings.');
+    } else {
+      console.log('');
+      console.log('Xcode download/installation failed.');
+      console.log('');
+      console.log('Error output:');
+      console.log(installResult.stderr || installResult.stdout || 'No error details available');
+      console.log('');
+      console.log('Troubleshooting:');
+      console.log('  1. Verify your Apple ID credentials are correct');
+      console.log('  2. If using two-factor authentication, generate an app-specific password:');
+      console.log('     https://appleid.apple.com/account/manage');
+      console.log('  3. Check available disk space (need ~50 GB free)');
+      console.log('  4. Try running manually:');
+      console.log('     xcodes install --latest');
+      console.log('');
+      console.log('To install a specific version:');
+      console.log('  xcodes list');
+      console.log('  xcodes install 16.2');
+      return;
+    }
+  }
+
+  // Verify Xcode is now installed
+  if (!isXcodeInstalled()) {
+    console.log('');
+    console.log('Download completed but Xcode was not found at /Applications/Xcode.app');
+    console.log('');
+    console.log('Please check:');
+    console.log('  1. Available disk space');
+    console.log('  2. Output from: xcodes installed');
+    console.log('  3. Contents of /Applications folder');
+    return;
+  }
+
+  console.log('');
+  console.log('Xcode downloaded and installed successfully.');
+  console.log('');
+
+  // Accept the Xcode license agreement
+  console.log('Accepting Xcode license agreement...');
+  const licenseResult = await shell.exec('sudo xcodebuild -license accept');
+  if (licenseResult.code !== 0) {
+    console.log('Warning: Could not automatically accept license.');
+    console.log('Please run manually: sudo xcodebuild -license accept');
+  }
+
+  // Run first-launch setup to install additional components
+  console.log('Installing additional components...');
+  const firstLaunchResult = await shell.exec('sudo xcodebuild -runFirstLaunch', {
+    timeout: 600000 // 10 minute timeout
+  });
+  if (firstLaunchResult.code !== 0) {
+    console.log('Warning: Could not complete first-launch setup.');
+    console.log('Please run manually: sudo xcodebuild -runFirstLaunch');
+  }
+
+  // Set the developer directory to point to the full Xcode installation
+  console.log('Setting active developer directory...');
+  const selectResult = await shell.exec(`sudo xcode-select -s "${XCODE_DEVELOPER_PATH}"`);
+  if (selectResult.code !== 0) {
+    console.log('Warning: Could not set developer directory.');
+    console.log(`Please run manually: sudo xcode-select -s "${XCODE_DEVELOPER_PATH}"`);
+  }
+
+  // Get and display the installed version
+  const installedVersion = await getXcodeVersion();
+  console.log('');
+  if (installedVersion) {
+    console.log(`Xcode ${installedVersion} installed successfully.`);
+  } else {
+    console.log('Xcode installed successfully.');
+  }
+  console.log('');
+  console.log('Post-installation notes:');
+  console.log('  1. Launch Xcode from /Applications or Spotlight to complete setup');
+  console.log('  2. Sign in with your Apple ID in Xcode > Settings > Accounts');
+  console.log('  3. Download additional simulators in Xcode > Settings > Platforms');
+  console.log('');
+  console.log('Verify installation:');
+  console.log('  xcodebuild -version');
+  console.log('  swift --version');
+  console.log('  xcode-select -p');
+}
 
 /**
- * Install Xcode Command Line Tools across supported platforms.
+ * Handle Xcode installation request on Ubuntu/Debian.
+ *
+ * Xcode is an Apple-exclusive product and is NOT available for Ubuntu or Debian.
+ * This function returns gracefully with a simple informational message.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_ubuntu() {
+  console.log('Xcode is not available for Ubuntu.');
+  return;
+}
+
+/**
+ * Handle Xcode installation request on Ubuntu running in WSL.
+ *
+ * Xcode is an Apple-exclusive product and cannot run in WSL. WSL runs a Linux
+ * kernel, not macOS, and cannot run macOS applications.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_ubuntu_wsl() {
+  console.log('Xcode is not available for WSL.');
+  return;
+}
+
+/**
+ * Handle Xcode installation request on Raspberry Pi OS.
+ *
+ * Xcode is an Apple-exclusive product and is NOT available for Raspberry Pi OS.
+ * The ARM architecture of Raspberry Pi is not compatible with Xcode, which only
+ * runs on macOS with Apple Silicon or Intel processors.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_raspbian() {
+  console.log('Xcode is not available for Raspberry Pi OS.');
+  return;
+}
+
+/**
+ * Handle Xcode installation request on Amazon Linux/RHEL.
+ *
+ * Xcode is an Apple-exclusive product and is NOT available for Amazon Linux
+ * or RHEL. Apple does not provide Xcode for any Linux distribution.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_amazon_linux() {
+  console.log('Xcode is not available for Amazon Linux.');
+  return;
+}
+
+/**
+ * Handle Xcode installation request on Windows.
+ *
+ * Xcode is an Apple-exclusive product and is NOT available for Windows.
+ * Apple does not provide Xcode for Windows, and there is no legitimate way
+ * to run Xcode on Windows.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_windows() {
+  console.log('Xcode is not available for Windows.');
+  return;
+}
+
+/**
+ * Handle Xcode installation request in Git Bash.
+ *
+ * Xcode is an Apple-exclusive product and is NOT available for Git Bash on
+ * Windows. Git Bash provides a Unix-like shell environment on Windows but
+ * cannot run macOS applications.
+ *
+ * @returns {Promise<void>}
+ */
+async function install_gitbash() {
+  console.log('Xcode is not available for Git Bash.');
+  return;
+}
+
+/**
+ * Check if Xcode is installed on the current system.
+ * @returns {Promise<boolean>} True if Xcode is installed
+ */
+async function isInstalled() {
+  const platform = os.detect();
+  if (platform.type === 'macos') {
+    return isXcodeInstalled();
+  }
+  return false;
+}
+
+/**
+ * Check if this installer is supported on the current platform.
+ * Xcode is ONLY available on macOS.
+ * @returns {boolean} True if installation is supported on this platform
+ */
+function isEligible() {
+  const platform = os.detect();
+  if (platform.type !== 'macos') {
+    return false;
+  }
+  if (REQUIRES_DESKTOP && !os.isDesktopAvailable()) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Main installation entry point - detects platform and runs appropriate installer.
+ *
+ * This function automatically detects the current operating system and invokes
+ * the corresponding platform-specific installation function. Since Xcode is
+ * macOS-only, all non-macOS platforms receive a polite informational message.
+ *
+ * Supported platforms:
+ * - macOS: Full Xcode IDE installation via xcodes
+ *
+ * Unsupported platforms (returns gracefully with message):
+ * - Ubuntu/Debian
+ * - Ubuntu on WSL
+ * - Raspberry Pi OS
+ * - Amazon Linux/RHEL/Fedora
+ * - Windows (native)
+ * - Git Bash
  *
  * @returns {Promise<void>}
  */
 async function install() {
   const platform = os.detect();
 
-  switch (platform.type) {
-    case 'macos':
-      // TODO: Implement macOS installation
-      break;
-    case 'debian':
-      // TODO: Implement Debian/Ubuntu installation
-      break;
-    case 'rhel':
-      // TODO: Implement RHEL/Amazon Linux installation
-      break;
-    case 'windows-wsl':
-      // TODO: Implement WSL installation
-      break;
-    case 'windows':
-      // TODO: Implement Windows installation
-      break;
-    default:
-      console.error(`Unsupported platform: ${platform.type}`);
-      process.exit(1);
-  }
-}
-
-module.exports = { install };
+  // Map platform types to their corresponding installer functions
+  // All non-macOS platforms will receive a "not available" message
+  const installers = {
+    'macos': install_macos,
+    'ubuntu': install_ubuntu,
+    'debian': install_ubuntu,
+    'wsl': install_ubuntu_wsl,
+    'raspbian': install_raspbian,
+    'amazon_linux': install_amazon_linux,
+    'fedora': install_amazon_linux,
+    'rhel': install_amazon_linux,
+    'windows': install_windows,
+    'gitbash': install_gitbash,
+  };
+
+  const installer = installers[platform.type];
+
+  // Handle unknown platforms gracefully without throwing an error
+  if (!installer) {
+    console.log(`Xcode is not available for ${platform.type}.`);
+    return;
+  }
+
+  await installer();
+}
+
+module.exports = {
+  REQUIRES_DESKTOP,
+  install,
+  isInstalled,
+  isEligible,
+  install_macos,
+  install_ubuntu,
+  install_ubuntu_wsl,
+  install_raspbian,
+  install_amazon_linux,
+  install_windows,
+  install_gitbash,
+};
 
 if (require.main === module) {
-  install();
+  install().catch(err => {
+    console.error(err.message);
+    process.exit(1);
+  });
 }