Maintain/Build/

Definition.rs

//=============================================================================//
// File Path: Element/Maintain/Source/Build/Definition.rs
//=============================================================================//
// Module: Definition
//
// Brief Description: Build system type definitions and data structures.
//
// RESPONSIBILITIES:
// ================
//
// Primary:
// - Define argument parsing structures
// - Define configuration file parsing structures
// - Define file guard structures
//
// Secondary:
// - Provide type-safe access to build configuration
//
// ARCHITECTURAL ROLE:
// ===================
//
// Position:
// - Infrastructure/Data structures layer
// - Type definitions
//
// Dependencies (What this module requires):
// - External crates: clap, serde, std (fs, log, path)
// - Internal modules: Constant
// - Traits implemented: Drop (for Guard), Parser (for Argument)
//
// Dependents (What depends on this module):
// - Build orchestration functions
// - Entry point functions
//
// IMPLEMENTATION DETAILS:
// =======================
//
// Design Patterns:
// - Builder pattern (via clap derive)
// - Data transfer object pattern
// - RAII pattern (Guard)
//
// Performance Considerations:
// - Complexity: O(n) - depends on operation
// - Memory usage patterns: Struct-based memory layout
// - Hot path optimizations: None
//
// Thread Safety:
// - Thread-safe: Yes (Argument derives Clone, Guard not thread-safe by design)
// - Synchronization mechanisms used: None
// - Interior mutability considerations: None
//
// Error Handling:
// - Error types returned: BuildError
// - Recovery strategies: Guard restores files on error
//
// EXAMPLES:
// =========
//
// Example 1: Parsing arguments
use std::{
	fs,
	path::{Path, PathBuf},
};

use clap::Parser;
use serde::Deserialize;
use log::{error, info};

/// ```rust
/// use clap::Parser;
///
/// use crate::Maintain::Source::Build::Definition;
/// let argument = Argument::parse();
/// println!("Building directory: {}", argument.Directory);
/// ```
// Example 2: Creating a guard
/// ```rust
/// use crate::Maintain::Source::Build::Definition;
/// let guard = Guard::New(file_path, description.to_string())?;
/// ```
// Example 3: Parsing cargo.toml
/// ```rust
/// use crate::Maintain::Source::Build::Definition;
/// let content = std::fs::read_to_string("Cargo.toml")?;
/// let manifest:Manifest = toml::from_str(&content)?;
/// ```
//
//=============================================================================//
// IMPLEMENTATION
//=============================================================================//
use crate::Build::Constant::*;

//=============================================================================
// Argument Definition
//=============================================================================

/// Represents parsed command-line arguments and environment variables that
/// control the build.
///
/// This struct is generated by `clap` from the `Parser` derive macro and
/// automatically parses command-line arguments and environment variables into
/// a strongly-typed configuration object. Each field can be configured via:
/// - Command-line arguments (long form, e.g., `--directory`)
/// - Environment variables (as specified in the `env` attribute)
/// - Default values (as specified in the `default_value` attribute)
///
/// Required fields must be provided, while optional fields can be omitted.
/// The `Command` field is special in that it accepts all remaining arguments
/// as the build command to execute.
///
/// # Field Descriptions
///
/// - **Directory**: The main directory of the project containing Cargo.toml
/// - **Name**: The original base name of the project/package
/// - **Prefix**: The prefix for the application's bundle identifier
/// - **Browser**: Flag for browser-specific build aspects
/// - **Bundle**: Flag for bundling-specific aspects
/// - **Compile**: Flag for compile-specific aspects
/// - **Clean**: Flag for cleaning-specific aspects
/// - **Debug**: Flag for debug-specific aspects
/// - **Dependency**: Information about a dependency (org/repo or boolean)
/// - **Environment**: The Node.js environment (development, production, etc.)
/// - **NodeVersion**: The Node.js sidecar version to bundle
/// - **Command**: The build command and its arguments to execute
#[derive(Parser, Debug, Clone)]
#[clap(
	author,
	version,
	about = "Prepares, builds, and restores project configurations."
)]
pub struct Argument {
	/// The main directory of the project.
	///
	/// This field specifies the project directory that contains the
	/// `Cargo.toml` and `tauri.conf.json` files. It can be set via:
	/// - Command-line: `--directory <path>`
	/// - Environment: `MOUNTAIN_DIR`
	/// - Default: "Element/Mountain"
	#[clap(long, env = DirEnv, default_value = DirectoryDefault)]
	pub Directory:String,

	/// The original base name of the project/package.
	///
	/// This field specifies the base name of the project, which serves as
	/// the suffix for generated product names. It can be set via:
	/// - Command-line: `--name <name>`
	/// - Environment: `MOUNTAIN_ORIGINAL_BASE_NAME`
	/// - Default: "Mountain"
	#[clap(long, env = NameEnv, default_value = NameDefault)]
	pub Name:String,

	/// The prefix for the application's bundle identifier.
	///
	/// This field specifies the reverse domain prefix for the bundle
	/// identifier. It can be set via:
	/// - Command-line: `--prefix <prefix>`
	/// - Environment: `MOUNTAIN_BUNDLE_ID_PREFIX`
	/// - Default: "land.editor.binary"
	#[clap(long, env = PrefixEnv, default_value = PrefixDefault)]
	pub Prefix:String,

	/// Flag or value indicating browser-specific build aspects.
	///
	/// When set to "true", enables browser-specific configuration and affects
	/// the generated product name and bundle identifier.
	#[clap(long, env = BrowserEnv)]
	pub Browser:Option<String>,

	/// Flag or value indicating bundling-specific aspects.
	///
	/// When set to "true", enables bundling-specific configuration and affects
	/// the generated product name and bundle identifier.
	#[clap(long, env = BundleEnv)]
	pub Bundle:Option<String>,

	/// Flag or value indicating compile-specific aspects.
	///
	/// When set to "true", enables compile-specific configuration and affects
	/// the generated product name and bundle identifier.
	#[clap(long, env = CompileEnv)]
	pub Compile:Option<String>,

	/// Flag or value indicating cleaning-specific aspects.
	///
	/// When set to "true", enables clean-specific configuration and affects
	/// the generated product name and bundle identifier.
	#[clap(long, env = CleanEnv)]
	pub Clean:Option<String>,

	/// Flag or value indicating debug-specific aspects.
	///
	/// When set to "true", enables debug-specific configuration and affects
	/// the generated product name and bundle identifier. Also automatically
	/// detected if the command contains "--debug".
	#[clap(long, env = DebugEnv)]
	pub Debug:Option<String>,

	/// Flag indicating the Mountain workbench profile (debug-mountain).
	/// Mutually exclusive with `Electron` and `Browser`; when set to "true"
	/// the product name gains a `_Mountain` suffix so Cargo/Tauri emit a
	/// distinct binary path that doesn't collide with other workbenches.
	#[clap(long, env = MountainEnv)]
	pub Mountain:Option<String>,

	/// Flag indicating the Electron workbench profile (debug-electron).
	/// Mutually exclusive with `Mountain` and `Browser`; adds a
	/// `_Electron` suffix to the generated product name + identifier.
	#[clap(long, env = ElectronEnv)]
	pub Electron:Option<String>,

	/// Compiler variant (e.g. "Rest"). When present the product name gains
	/// a `_Compiler<Name>` suffix so variant compilers don't collide with
	/// the default TypeScript/tsc path.
	#[clap(long, env = CompilerEnv)]
	pub Compiler:Option<String>,

	/// Comma-joined Cargo features derived from `.env.Land` tier selections
	/// by `Maintain/Script/TierEnvironment.sh`. When present and the build
	/// command is `pnpm tauri build [--debug]`, these are forwarded to Cargo
	/// via `-- --features "<list>"` so tier-gated Rust code compiles in.
	/// Example: "TierRemoteProcedureCallSharedMemory,TierLoggerRing".
	#[clap(long, env = CargoFeaturesEnv)]
	pub CargoFeatures:Option<String>,

	/// JSON blob of `__LandTier_<Capability>__` replacement tokens produced
	/// by `Maintain/Script/TierEnvironment.sh`. Cocoon's `TargetConfig.ts`
	/// merges it into its esbuild `define` options so tier constants compile
	/// into the Cocoon bundle. Maintain only needs to pass it through to
	/// the child process environment - no parsing happens here.
	#[clap(long, env = CocoonEsbuildDefineEnv)]
	pub CocoonEsbuildDefine:Option<String>,

	/// Information about a dependency, often 'org/repo' or a boolean string.
	///
	/// This field specifies dependency information that affects the generated
	/// product name and bundle identifier. Can be:
	/// - "true" for generic dependencies
	/// - "org/repo" for specific repository dependencies
	/// - Any custom string
	#[clap(long, env = DependencyEnv)]
	pub Dependency:Option<String>,

	/// The Node.js environment (e.g., "development", "production").
	///
	/// This field specifies the Node.js runtime environment and affects the
	/// generated product name and bundle identifier.
	#[clap(long, env = NodeEnv)]
	pub Environment:Option<String>,

	/// Specifies the Node.js sidecar version to bundle (e.g., "22").
	///
	/// This field specifies which Node.js version should be bundled as a
	/// sidecar binary with the application. The executable is sourced from
	/// the Element/SideCar directory.
	#[clap(long, env = NodeVersionEnv)]
	pub NodeVersion:Option<String>,

	/// The build command and its arguments to execute.
	///
	/// This field accepts all remaining command-line arguments as the build
	/// command to execute after configuring the project files. This field
	/// is required and must be provided as the final arguments.
	///
	/// Example: `pnpm tauri build`
	#[clap(required = true, last = true)]
	pub Command:Vec<String>,
}

//=============================================================================
// Guard Definition (RAII Pattern)
//=============================================================================

/// Manages the backup and restoration of a single file using the RAII pattern.
///
/// This struct ensures that an original file is restored to its initial state
/// when the Guard goes out of scope, providing a safe way to temporarily
/// modify configuration files during the build process.
///
/// # RAII Pattern
///
/// The Guard implements the RAII (Resource Acquisition Is Initialization)
/// pattern:
/// - **Acquisition**: When created, it creates a backup of the original file
/// - **Release**: When dropped, it restores the original file from the backup
///
/// This ensures that files are restored even if:
/// - The function returns early
/// - An error occurs and propagates up
/// - A panic occurs
///
/// # Backup Naming
///
/// Backup files are created by appending a suffix to the original file
/// extension:
/// - `Cargo.toml` → `Cargo.toml.Backup`
/// - `tauri.conf.json` → `tauri.conf.json.Backup`
///
/// # Error Handling
///
/// The Guard constructor returns an error if:
/// - A backup file already exists at the target location
/// - The original file cannot be copied (IO error)
///
/// This prevents accidental overwriting of existing backups and ensures
/// data safety.
///
/// # Fields
///
/// - **Path**: The path to the original file
/// - **Store**: The path to the backup file
/// - **Active**: Whether a backup was created
/// - **Note**: A descriptive note for logging purposes
pub struct Guard {
	/// The path to the original file that will be modified.
	Path:PathBuf,

	/// The path to the backup file created by this guard.
	Store:PathBuf,

	/// Whether a backup was actually created
	/// (false if the original file didn't exist).
	Active:bool,

	/// Whether the guard is armed to restore on drop.
	/// When true, the file will be restored on drop.
	/// When false (disarmed), the modified file is preserved.
	Armed:bool,

	/// A descriptive note for logging and debugging purposes.
	Note:String,
}

impl Guard {
	/// Creates a new Guard that backs up the specified file.
	///
	/// This constructor creates a backup of the original file if it exists,
	/// and prepares to restore it when the Guard is dropped. The backup
	/// file is created with a special suffix to prevent accidental conflicts.
	///
	/// # Parameters
	///
	/// * `OriginalPath` - The path to the file to be backed up
	/// * `Description` - A descriptive note for logging purposes
	///
	/// # Returns
	///
	/// Returns a `Result` containing the Guard or a `BuildError` if:
	/// - A backup file already exists
	/// - The file cannot be copied
	///
	/// # Errors
	///
	/// * `BuildError::Exists` - If a backup file already exists
	/// * `BuildError::Io` - If the file copy operation fails
	///
	/// # Example
	///
	/// ```no_run
	/// use crate::Maintain::Source::Build::Definition;
	/// let path = PathBuf::from("Cargo.toml");
	/// let guard = Guard::New(path, "Cargo manifest".to_string())?;
	/// ```
	///
	/// # Safety
	///
	/// The Guard ensures that the original file is restored even in the
	/// presence of panics, providing exception safety.
	pub fn New(OriginalPath:PathBuf, Description:String) -> Result<Self, crate::Build::Error::Error> {
		let BackupPath = OriginalPath.with_extension(format!(
			"{}{}",
			OriginalPath.extension().unwrap_or_default().to_str().unwrap_or(""),
			BackupSuffix
		));

		if BackupPath.exists() {
			error!("Backup file {} already exists.", BackupPath.display());

			return Err(crate::Build::Error::Error::Exists(BackupPath));
		}

		let mut BackupMade = false;

		if OriginalPath.exists() {
			fs::copy(&OriginalPath, &BackupPath)?;

			info!(
				target: "Build::Guard",

				"Backed {} to {}",

				OriginalPath.display(),

				BackupPath.display()
			);

			BackupMade = true;
		}

		Ok(Self {
			Path:OriginalPath,
			Store:BackupPath,
			Active:BackupMade,
			Armed:true,
			Note:Description,
		})
	}

	/// Returns a reference to the original file path.
	///
	/// This method provides read access to the path of the original file
	/// that this guard is protecting.
	///
	/// # Returns
	///
	/// A reference to the original file's `Path`.
	///
	/// # Example
	///
	/// ```no_run
	/// use crate::Maintain::Source::Build::Definition;
	/// let guard = Guard::New(original_path, description.to_string())?;
	/// println!("Original file: {}", guard.Path().display());
	/// ```
	pub fn Path(&self) -> &Path { &self.Path }

	/// Returns a reference to the backup file path.
	///
	/// This method provides read access to the path where the backup
	/// file is stored.
	///
	/// # Returns
	///
	/// A reference to the backup file's `Path`.
	///
	/// # Example
	///
	/// ```no_run
	/// use crate::Maintain::Source::Build::Definition;
	/// let guard = Guard::New(original_path, description.to_string())?;
	/// println!("Backup file: {}", guard.Store().display());
	/// ```
	pub fn Store(&self) -> &Path { &self.Store }

	/// Disarms the guard, preventing restoration of the original file,
	/// and deletes the backup so the next build is not blocked.
	pub fn disarm(&mut self) {
		self.Armed = false;

		if self.Active && self.Store.exists() {
			let _ = fs::remove_file(&self.Store);
		}
	}
}

/// Drop implementation that automatically restores the original file.
///
/// This is the core of the RAII pattern: when the Guard goes out of scope,
/// it automatically restores the original file from the backup. This ensures
/// that file modifications are temporary and that the system is left in a
/// consistent state even if an error occurs.
///
/// # Behavior
///
/// - If no backup was created (original file didn't exist), does nothing
/// - If backup exists, copies it back to the original location
/// - After successful restore, deletes the backup file
/// - Logs success or failure of the restoration process
///
/// # Panics
///
/// This implementation handles panics internally and does not propagate them.
/// If the restoration fails, it logs an error but does not panic, ensuring
/// that cleanup failures don't cause secondary failures.
impl Drop for Guard {
	fn drop(&mut self) {
		// Only restore if armed (build failed) and backup is active
		if self.Armed && self.Active && self.Store.exists() {
			info!(
				target: "Build::Guard",

				"Restoring {} from {}...",

				self.Path.display(),

				self.Store.display()
			);

			if let Ok(_) = fs::copy(&self.Store, &self.Path) {
				info!(target: "Build::Guard", "Restore successful.");

				if let Err(e) = fs::remove_file(&self.Store) {
					error!(
						target: "Build::Guard",

						"Failed to delete backup {}: {}",

						self.Store.display(),

						e
					);
				}
			} else if let Err(e) = fs::copy(&self.Store, &self.Path) {
				error!(
					target: "Build::Guard",

					"Restore FAILED: {}. {} is now inconsistent.",

					e,

					self.Path.display()
				);
			}
		}
	}
}

//=============================================================================
// Manifest Definition
//=============================================================================

/// Represents the `package` section of a `Cargo.toml` manifest.
///
/// This struct contains metadata extracted from the `[package]` section
/// of a Cargo.toml file. It is used for deserializing TOML content using
/// the `toml` crate's deserialization functionality.
///
/// Currently, this struct only extracts the version information, which
/// is needed for updating the Tauri configuration file with the correct
/// version during the build process.
///
/// # TOML Format
///
/// The expected TOML structure:
/// ```toml
/// [package]
/// name = "Mountain"
/// version = "1.0.0"
/// # ... other fields
/// ```
///
/// # Fields
///
/// - **package**: Contains the metadata extracted from the package section
#[derive(Deserialize, Debug)]
pub struct Manifest {
	/// Represents metadata within the `package` section of `Cargo.toml`.
	///
	/// This nested struct contains the individual metadata fields from the
	/// package section, including the version string.
	package:Meta,
}

impl Manifest {
	/// Retrieves the version string from the manifest.
	///
	/// This method provides access to the version field, which is stored
	/// privately. The version is used when updating the Tauri configuration
	/// file during the build process.
	///
	/// # Returns
	///
	/// A string slice containing the version number.
	///
	/// # Example
	///
	/// ```no_run
	/// use crate::Maintain::Source::Build::Definition;
	/// let version = manifest.get_version();
	/// println!("Application version: {}", version);
	/// ```
	pub fn get_version(&self) -> &str { &self.package.version }
}

/// Represents metadata within the `package` section of `Cargo.toml`.
///
/// This struct contains individual metadata fields from the package section.
/// Currently, only the version field is stored, but additional fields can
/// be added as needed (e.g., name, description, authors, etc.).
///
/// All fields are private and should be accessed through methods on the
/// parent `Manifest` struct.
#[derive(Deserialize, Debug)]
struct Meta {
	/// The version string from the package metadata.
	///
	/// This field contains the version identifier as specified in the
	/// Cargo.toml file (e.g., "1.0.0", "2.3.4-beta.1").
	version:String,
}