XtafProgram.cs

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Linq;
using System.Reflection;
using System.Threading;
using Fsp;
using Microsoft.Win32;

namespace Xtaf
{
    internal sealed class CommandLineUsageException : Exception
    {
        public CommandLineUsageException(string message = null) : base(message)
        {
        }
    }

    internal sealed class WinFspRuntimeException : Exception
    {
        public WinFspRuntimeException(string message, Exception innerException = null) : base(message, innerException)
        {
        }
    }

    internal sealed class MountSession : IDisposable
    {
        readonly List<FileSystemHost> hosts = new List<FileSystemHost>();
        readonly List<MountedVolumeInfo> volumes = new List<MountedVolumeInfo>();
        readonly List<SkippedPartitionInfo> skippedPartitions = new List<SkippedPartitionInfo>();

        public MountSession(Stream stream)
        {
            Stream = stream;
        }

        public Stream Stream { get; private set; }
        public IList<MountedVolumeInfo> Volumes { get { return volumes.AsReadOnly(); } }
        public IList<SkippedPartitionInfo> SkippedPartitions { get { return skippedPartitions.AsReadOnly(); } }

        public void Add(FileSystemHost host, string fsType, string logicalName)
        {
            hosts.Add(host);
            volumes.Add(new MountedVolumeInfo
            {
                FileSystemType = fsType,
                LogicalName = logicalName,
                MountPoint = host.MountPoint()
            });
        }

        public void AddSkippedPartition(PartitionCandidate partition, string reason)
        {
            skippedPartitions.Add(new SkippedPartitionInfo
            {
                Name = partition == null ? "Unknown" : partition.Name,
                Offset = partition == null ? 0 : partition.Offset,
                Reason = string.IsNullOrWhiteSpace(reason) ? "mount failed" : reason
            });
        }

        public void Dispose()
        {
            for (int i = hosts.Count - 1; i >= 0; i--)
            {
                Program.DisposeHost(hosts[i]);
            }
            hosts.Clear();

            if (Stream != null)
            {
                Stream.Dispose();
                Stream = null;
            }
        }
    }

    internal static class Program
    {
        const string ProgramName = "xtaf";
        const int AutoScanStep = 0x1000;
        const int MaxRecoveredPartitions = 32;

        internal delegate bool PartitionMountAttempt(
            MountSession session,
            MountOptions options,
            PartitionCandidate partition,
            string mountPoint,
            object streamLock,
            bool continueOnFailure,
            out string failureReason);

        static Program()
        {
            AppDomain.CurrentDomain.AssemblyResolve += ResolveWinFspAssembly;
        }

        static readonly PartitionProfileEntry[] KnownPartitions = new[]
        {
            new PartitionProfileEntry("cache0", "Cache Partition 0", 0x00080000L, 0x80000000L),
            new PartitionProfileEntry("cache1", "Cache Partition 1", 0x80080000L, 0x80000000L),
            new PartitionProfileEntry("recoveryaux", "Recovery Partition (Aux)", 0x10C080000L, 0x0CE30000L),
            new PartitionProfileEntry("recovery", "Recovery Partition (Ext)", 0x118EB0000L, 0x08000000L),
            new PartitionProfileEntry("backcompat", "Backward Compatibility", 0x120EB0000L, 0x10000000L),
            new PartitionProfileEntry("content", "Content", 0x130EB0000L, 0),
            new PartitionProfileEntry("systemext", "System Extended", 0x10000000L, 0x04000000L),
            new PartitionProfileEntry("systemaux", "System Auxiliary", 0x14000000L, 0x10000000L),
            new PartitionProfileEntry("backcompat", "Compatibility", 0x24000000L, 0x20C000000L),
            new PartitionProfileEntry("content", "Content", 0x230000000L, 0x2D0000000L),
            new PartitionProfileEntry("systempartition", "SystemPartition", 0x2A0EB0000L, 0x10000000L),
            new PartitionProfileEntry("content", "Content", 0x2B0EB0000L, 0x183DAC6000L),
            new PartitionProfileEntry("mucache", "MU Cache", 0x00000000L, 0x007FF000L),
            new PartitionProfileEntry("mucontent", "MU Content", 0x007FF000L, 0)
        };

        static readonly string[] DefaultPriority = new[]
        {
            "content", "mucontent", "backcompat", "systemext", "systemaux", "recovery", "recoveryaux", "cache0", "cache1", "mucache"
        };

        static int Main(string[] args)
        {
            try
            {
                MountOptions options = ParseArgs(args);
                bool recoveryRequested = XtafRecoveryEngine.IsRecoveryRequested(options);
                bool sizeAuditRequested = options.AnalyzeImageSize || !string.IsNullOrWhiteSpace(options.TrimImageOutputPath);
                bool volumeOpsRequested = options.VolumeStats || !string.IsNullOrWhiteSpace(options.ExtractVolumePath);
                if (options.ShowHelp)
                {
                    PrintUsage();
                    return 0;
                }

                if (!File.Exists(options.ImagePath))
                    throw new CommandLineUsageException("Image file was not found.");

                bool assistOnly = options.DiskpartAssist &&
                    !options.ListPartitions &&
                    !options.MountAllPartitions &&
                    string.IsNullOrWhiteSpace(options.PartitionSelector) &&
                    string.IsNullOrWhiteSpace(options.MountPoint) &&
                    string.IsNullOrWhiteSpace(options.MountRoot);

                if (options.ListPartitions || options.DiskpartAssist || recoveryRequested)
                {
                    using (Stream scan = OpenImageStream(options.ImagePath, options.Features))
                    {
                        List<PartitionCandidate> partitions = DiscoverPartitions(scan, options.Features);
                        if (options.ListPartitions || options.DiskpartAssist)
                            PrintPartitions(partitions, options.ImagePath);
                        if (options.DiskpartAssist)
                            PrintDiskpartAssist(options.ImagePath, partitions);

                        if (recoveryRequested)
                        {
                            XtafRecoveryEngine.Run(options, scan, partitions);
                            return 0;
                        }
                    }

                    if ((options.ListPartitions || assistOnly) && !sizeAuditRequested && !volumeOpsRequested)
                        return 0;
                }

                if (sizeAuditRequested)
                {
                    RunImageAuditAndTrim(options);
                    return 0;
                }

                if (volumeOpsRequested)
                {
                    RunVolumeOperations(options);
                    return 0;
                }

                PrepareWinFspRuntime(options.DebugLogFile);

                using (MountSession session = Mount(options))
                {
                    PrintMounts(options.ImagePath, session);
                    WaitForCtrlC();
                }

                return 0;
            }
            catch (CommandLineUsageException ex)
            {
                if (!string.IsNullOrWhiteSpace(ex.Message))
                {
                    Console.Error.WriteLine("Error: {0}", ex.Message);
                    Console.Error.WriteLine();
                }
                PrintUsage();
                return 2;
            }
            catch (WinFspRuntimeException ex)
            {
                Console.Error.WriteLine("Error: {0}", ex.Message);
                return 2;
            }
            catch (Exception ex)
            {
                string winFspMessage;
                if (TryFormatWinFspInteropError(ex, out winFspMessage))
                {
                    Console.Error.WriteLine("Error: {0}", winFspMessage);
                    return 2;
                }

                Console.Error.WriteLine("Error: {0}", ex.Message);
                return 1;
            }
        }

        static MountOptions ParseArgs(string[] args)
        {
            var options = new MountOptions();

            for (int i = 0; i < args.Length; i++)
            {
                string arg = args[i];
                if (arg == "-?" || arg == "--help" || arg == "/?")
                {
                    options.ShowHelp = true;
                    return options;
                }

                if (!arg.StartsWith("-", StringComparison.Ordinal))
                    throw new CommandLineUsageException(string.Format("Unknown positional argument '{0}'.", arg));

                switch (arg)
                {
                    case "-d":
                    {
                        int parsed;
                        if (!int.TryParse(NextArg(args, ref i, arg), out parsed))
                            throw new CommandLineUsageException("Debug flags must be an integer.");
                        options.DebugFlags = unchecked((uint)parsed);
                        break;
                    }
                    case "-D": options.DebugLogFile = NextArg(args, ref i, arg); break;
                    case "-i": options.ImagePath = NextArg(args, ref i, arg); break;
                    case "-m": options.MountPoint = NextArg(args, ref i, arg); break;
                    case "-p":
                    case "--partition": options.PartitionSelector = NextArg(args, ref i, arg); break;
                    case "-a":
                    case "--all-partitions": options.MountAllPartitions = true; break;
                    case "-l":
                    case "--list-partitions": options.ListPartitions = true; break;
                    case "--mount-root": options.MountRoot = NextArg(args, ref i, arg); break;
                    case "--diskpart": options.DiskpartAssist = true; break;
                    case "--read-only": options.Features.ReadOnly = true; break;
                    case "--recovery-mode": options.Features.RecoveryMode = true; break;
                    case "--f-takes-all-override": options.Features.FTakesAllOverride = true; break;
                    case "--disable-disk-cache": options.Features.DisableDiskCache = true; break;
                    case "--ignore-security-sector": options.Features.IgnoreSecuritySector = true; break;
                    case "--restore-partition-table": options.Features.RestorePartitionTable = true; break;
                    case "--metadata-scan": options.ScanMetadata = true; break;
                    case "--metadata-scan-limit": options.MetadataScanLimitBytes = ParseByteCountOption(NextArg(args, ref i, arg), arg); break;
                    case "--recover-deleted": options.RecoverDeletedFiles = true; break;
                    case "--carve-files": options.CarveFiles = true; break;
                    case "--carve-deep": options.CarveDeepScan = true; break;
                    case "--recovery-output": options.RecoveryOutputPath = NextArg(args, ref i, arg); break;
                    case "--carve-interval": options.CarveInterval = ParseCarveInterval(NextArg(args, ref i, arg)); break;
                    case "--analyze-image-size": options.AnalyzeImageSize = true; break;
                    case "--trim-image": options.TrimImageOutputPath = NextArg(args, ref i, arg); break;
                    case "--trim-block-mib":
                    {
                        int parsed;
                        if (!int.TryParse(NextArg(args, ref i, arg), out parsed))
                            throw new CommandLineUsageException("Trim block size must be an integer number of MiB.");
                        options.TrimBlockMiB = parsed;
                        break;
                    }
                    case "--volume-offset":
                        options.VolumeOffset = ParseLongOption(NextArg(args, ref i, arg), "--volume-offset");
                        break;
                    case "--volume-length":
                        options.VolumeLength = ParseLongOption(NextArg(args, ref i, arg), "--volume-length");
                        break;
                    case "--volume-stats":
                        options.VolumeStats = true;
                        break;
                    case "--extract-volume":
                        options.ExtractVolumePath = NextArg(args, ref i, arg);
                        break;
                    default: throw new CommandLineUsageException(string.Format("Unknown option '{0}'.", arg));
                }
            }

            if (string.IsNullOrWhiteSpace(options.ImagePath))
                throw new CommandLineUsageException("Image path is required.");
            if (options.MountAllPartitions && !string.IsNullOrWhiteSpace(options.PartitionSelector))
                throw new CommandLineUsageException("Use either --all-partitions or --partition.");
            if (options.CarveDeepScan)
                options.CarveFiles = true;
            if (options.RecoverDeletedFiles)
                options.ScanMetadata = true;
            if (options.MetadataScanLimitBytes > 0 && !options.ScanMetadata && !options.RecoverDeletedFiles && !options.CarveFiles)
                throw new CommandLineUsageException("--metadata-scan-limit requires --metadata-scan, --recover-deleted, or --carve-files.");
            if (!string.IsNullOrWhiteSpace(options.TrimImageOutputPath))
                options.AnalyzeImageSize = true;
            if (options.TrimBlockMiB < 1 || options.TrimBlockMiB > 256)
                throw new CommandLineUsageException("--trim-block-mib must be between 1 and 256.");
            if (!string.IsNullOrWhiteSpace(options.TrimImageOutputPath) &&
                string.Equals(Path.GetFullPath(options.TrimImageOutputPath), Path.GetFullPath(options.ImagePath), StringComparison.OrdinalIgnoreCase))
                throw new CommandLineUsageException("--trim-image output path must be different from input image path.");
            if (options.VolumeLength < 0)
                throw new CommandLineUsageException("--volume-length must be non-negative.");
            if (options.VolumeLength > 0 && options.VolumeOffset < 0)
                throw new CommandLineUsageException("--volume-length requires --volume-offset.");
            if (!string.IsNullOrWhiteSpace(options.ExtractVolumePath) &&
                string.Equals(Path.GetFullPath(options.ExtractVolumePath), Path.GetFullPath(options.ImagePath), StringComparison.OrdinalIgnoreCase))
                throw new CommandLineUsageException("--extract-volume output path must be different from input image path.");

            bool recoveryRequested = XtafRecoveryEngine.IsRecoveryRequested(options);
            bool sizeAuditRequested = options.AnalyzeImageSize || !string.IsNullOrWhiteSpace(options.TrimImageOutputPath);
            bool volumeOpsRequested = options.VolumeStats || !string.IsNullOrWhiteSpace(options.ExtractVolumePath);

            bool assistOnly = options.DiskpartAssist &&
                !options.ListPartitions &&
                !options.MountAllPartitions &&
                string.IsNullOrWhiteSpace(options.PartitionSelector) &&
                string.IsNullOrWhiteSpace(options.MountPoint) &&
                string.IsNullOrWhiteSpace(options.MountRoot);

            if (!options.ListPartitions && !assistOnly && !recoveryRequested && !sizeAuditRequested && !volumeOpsRequested)
            {
                if (options.MountAllPartitions && string.IsNullOrWhiteSpace(options.MountPoint) && string.IsNullOrWhiteSpace(options.MountRoot))
                    options.MountPoint = "*";

                if (!options.MountAllPartitions && string.IsNullOrWhiteSpace(options.MountPoint))
                    throw new CommandLineUsageException("Mount point is required.");
            }

            if (!string.IsNullOrWhiteSpace(options.MountRoot) && !options.MountAllPartitions)
                throw new CommandLineUsageException("--mount-root requires --all-partitions.");

            return options;
        }

        static string NextArg(string[] args, ref int index, string option)
        {
            if (index + 1 >= args.Length)
                throw new CommandLineUsageException(string.Format("Missing value for {0}.", option));
            index++;
            return args[index];
        }

        static RecoveryCarveInterval ParseCarveInterval(string token)
        {
            if (string.IsNullOrWhiteSpace(token))
                throw new CommandLineUsageException("Carve interval value is required.");

            switch (token.Trim().ToLowerInvariant())
            {
                case "byte":
                case "1":
                    return RecoveryCarveInterval.Byte;
                case "align":
                case "0x10":
                case "16":
                    return RecoveryCarveInterval.Align;
                case "sector":
                case "0x200":
                case "512":
                    return RecoveryCarveInterval.Sector;
                case "page":
                case "0x1000":
                case "4096":
                    return RecoveryCarveInterval.Page;
                case "cluster":
                case "0x4000":
                case "16384":
                    return RecoveryCarveInterval.Cluster;
                default:
                    throw new CommandLineUsageException("Invalid carve interval. Use byte|align|sector|page|cluster.");
            }
        }

        static long ParseLongOption(string token, string option)
        {
            if (string.IsNullOrWhiteSpace(token))
                throw new CommandLineUsageException(string.Format("Missing value for {0}.", option));

            string trimmed = token.Trim();
            long value;
            if (trimmed.StartsWith("0x", StringComparison.OrdinalIgnoreCase))
            {
                if (!long.TryParse(trimmed.Substring(2), System.Globalization.NumberStyles.HexNumber, System.Globalization.CultureInfo.InvariantCulture, out value))
                    throw new CommandLineUsageException(string.Format("Invalid hex value for {0}.", option));
            }
            else
            {
                if (!long.TryParse(trimmed, out value))
                    throw new CommandLineUsageException(string.Format("Invalid numeric value for {0}.", option));
            }

            if (value < 0)
                throw new CommandLineUsageException(string.Format("{0} must be non-negative.", option));
            return value;
        }

        static long ParseByteCountOption(string token, string option)
        {
            if (string.IsNullOrWhiteSpace(token))
                throw new CommandLineUsageException(string.Format("Missing value for {0}.", option));

            string trimmed = token.Trim();
            int suffixStart = trimmed.Length;
            while (suffixStart > 0 && char.IsLetter(trimmed[suffixStart - 1]))
                suffixStart--;

            string number = trimmed.Substring(0, suffixStart).Trim();
            string suffix = trimmed.Substring(suffixStart).Trim().ToLowerInvariant();
            if (string.IsNullOrWhiteSpace(number))
                throw new CommandLineUsageException(string.Format("Invalid byte count for {0}.", option));

            long multiplier;
            switch (suffix)
            {
                case "":
                case "b":
                case "byte":
                case "bytes":
                    multiplier = 1;
                    break;
                case "k":
                case "kb":
                case "kib":
                    multiplier = 1024L;
                    break;
                case "m":
                case "mb":
                case "mib":
                    multiplier = 1024L * 1024L;
                    break;
                case "g":
                case "gb":
                case "gib":
                    multiplier = 1024L * 1024L * 1024L;
                    break;
                default:
                    throw new CommandLineUsageException(string.Format("Invalid byte-count suffix for {0}. Use bytes, KiB, MiB, or GiB.", option));
            }

            long value;
            if (number.StartsWith("0x", StringComparison.OrdinalIgnoreCase))
            {
                if (!long.TryParse(number.Substring(2), System.Globalization.NumberStyles.HexNumber, System.Globalization.CultureInfo.InvariantCulture, out value))
                    throw new CommandLineUsageException(string.Format("Invalid hex value for {0}.", option));
            }
            else
            {
                if (!long.TryParse(number, out value))
                    throw new CommandLineUsageException(string.Format("Invalid numeric value for {0}.", option));
            }

            if (value <= 0)
                throw new CommandLineUsageException(string.Format("{0} must be positive.", option));
            if (value > long.MaxValue / multiplier)
                throw new CommandLineUsageException(string.Format("{0} is too large.", option));
            return value * multiplier;
        }

        static void RunImageAuditAndTrim(MountOptions options)
        {
            int blockBytes = options.TrimBlockMiB * 1024 * 1024;
            ImageSizeAuditResult audit = AnalyzeImageSize(options.ImagePath, blockBytes);
            PrintImageSizeAudit(options.ImagePath, audit);

            if (string.IsNullOrWhiteSpace(options.TrimImageOutputPath))
                return;

            if (audit.TrailingZeroBytes <= 0)
            {
                Console.WriteLine("No trailing-zero bloat detected. Trim output was not created.");
                Console.WriteLine();
                return;
            }

            string outputPath = Path.GetFullPath(options.TrimImageOutputPath);
            string outputDir = Path.GetDirectoryName(outputPath);
            if (!string.IsNullOrWhiteSpace(outputDir))
                Directory.CreateDirectory(outputDir);

            TrimImageToSize(options.ImagePath, outputPath, audit.SuggestedTrimSize, blockBytes);
            Console.WriteLine("Trimmed image written: {0}", outputPath);
            Console.WriteLine("Trimmed bytes: {0:N0}", audit.TrailingZeroBytes);
            Console.WriteLine();
        }

        static ImageSizeAuditResult AnalyzeImageSize(string imagePath, int blockSizeBytes)
        {
            var result = new ImageSizeAuditResult
            {
                BlockSizeBytes = blockSizeBytes
            };

            using (var stream = new FileStream(imagePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1024 * 1024, FileOptions.SequentialScan))
            {
                result.LogicalSize = stream.Length;
                if (result.LogicalSize == 0)
                {
                    result.SuggestedTrimSize = 0;
                    result.TrailingZeroBytes = 0;
                    return result;
                }

                result.TotalBlocks = (result.LogicalSize + blockSizeBytes - 1) / blockSizeBytes;
                byte[] buffer = new byte[blockSizeBytes];

                long offset = 0;
                long blockIndex = 0;
                while (offset < result.LogicalSize)
                {
                    int toRead = (int)Math.Min(blockSizeBytes, result.LogicalSize - offset);
                    if (!ReadFully(stream, buffer, 0, toRead))
                        throw new IOException("Unexpected end-of-stream while analyzing image size.");

                    bool allZero = true;
                    int lastNonZero = -1;
                    for (int i = 0; i < toRead; i++)
                    {
                        if (buffer[i] != 0)
                        {
                            allZero = false;
                            lastNonZero = i;
                        }
                    }

                    if (allZero)
                    {
                        result.ZeroBlocks++;
                    }
                    else
                    {
                        result.LastNonZeroOffset = offset + lastNonZero;
                    }

                    blockIndex++;
                    offset += toRead;
                    if ((blockIndex % 512) == 0 || offset >= result.LogicalSize)
                    {
                        double percent = result.LogicalSize == 0 ? 100.0 : (100.0 * offset / result.LogicalSize);
                        Console.WriteLine("Size audit progress: {0:N1}% ({1:N0}/{2:N0} bytes)", percent, offset, result.LogicalSize);
                    }
                }
            }

            result.SuggestedTrimSize = result.LastNonZeroOffset >= 0 ? result.LastNonZeroOffset + 1 : 0;
            result.TrailingZeroBytes = Math.Max(0, result.LogicalSize - result.SuggestedTrimSize);
            return result;
        }

        static void PrintImageSizeAudit(string imagePath, ImageSizeAuditResult audit)
        {
            Console.WriteLine();
            Console.WriteLine("Image size audit: {0}", imagePath);
            Console.WriteLine("Logical size:     {0:N0} bytes ({1:N2} GiB)", audit.LogicalSize, audit.LogicalSize / 1024.0 / 1024.0 / 1024.0);
            Console.WriteLine("Block size:       {0:N0} bytes ({1} MiB)", audit.BlockSizeBytes, audit.BlockSizeBytes / 1024 / 1024);
            Console.WriteLine("Total blocks:     {0:N0}", audit.TotalBlocks);
            Console.WriteLine("Zero blocks:      {0:N0} ({1:N2}%)",
                audit.ZeroBlocks,
                audit.TotalBlocks == 0 ? 0.0 : (100.0 * audit.ZeroBlocks / audit.TotalBlocks));
            Console.WriteLine("Last non-zero:    {0}", audit.LastNonZeroOffset >= 0 ? string.Format("0x{0:X}", audit.LastNonZeroOffset) : "none");
            Console.WriteLine("Trim candidate:   {0:N0} bytes ({1:N2} GiB)",
                audit.SuggestedTrimSize,
                audit.SuggestedTrimSize / 1024.0 / 1024.0 / 1024.0);
            Console.WriteLine("Trailing zeros:   {0:N0} bytes ({1:N2} GiB)",
                audit.TrailingZeroBytes,
                audit.TrailingZeroBytes / 1024.0 / 1024.0 / 1024.0);
            Console.WriteLine();
        }

        static void TrimImageToSize(string sourcePath, string outputPath, long length, int bufferBytes)
        {
            using (var source = new FileStream(sourcePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1024 * 1024, FileOptions.SequentialScan))
            using (var output = new FileStream(outputPath, FileMode.Create, FileAccess.Write, FileShare.None, 1024 * 1024, FileOptions.SequentialScan))
            {
                byte[] buffer = new byte[Math.Max(1024 * 1024, bufferBytes)];
                long remaining = length;
                while (remaining > 0)
                {
                    int toRead = (int)Math.Min(buffer.Length, remaining);
                    int read = source.Read(buffer, 0, toRead);
                    if (read <= 0)
                        throw new IOException("Unexpected end-of-stream while trimming image.");
                    output.Write(buffer, 0, read);
                    remaining -= read;
                }
                output.SetLength(length);
            }
        }

        static bool ReadFully(Stream stream, byte[] buffer, int offset, int count)
        {
            int total = 0;
            while (total < count)
            {
                int read = stream.Read(buffer, offset + total, count - total);
                if (read <= 0)
                    return false;
                total += read;
            }
            return true;
        }

        static void RunVolumeOperations(MountOptions options)
        {
            using (Stream stream = OpenImageStream(options.ImagePath, options.Features))
            {
                List<PartitionCandidate> discovered = DiscoverPartitions(stream, options.Features);
                PartitionCandidate target = ResolveVolumeTarget(options, discovered, stream.Length);
                if (target == null)
                    throw new CommandLineUsageException("No volume target was found. Use --volume-offset or --partition.");

                long maxLength = Math.Max(0, stream.Length - target.Offset);
                if (target.Size <= 0 || target.Size > maxLength)
                    target.Size = maxLength;

                Console.WriteLine();
                Console.WriteLine("Volume target:");
                Console.WriteLine("  Name:   {0}", target.Name);
                Console.WriteLine("  Offset: 0x{0:X}", target.Offset);
                Console.WriteLine("  Length: 0x{0:X} ({1:N2} GiB)", target.Size, target.Size / 1024.0 / 1024.0 / 1024.0);

                PrintVolumeStats(stream, target, options.Features);

                if (!string.IsNullOrWhiteSpace(options.ExtractVolumePath))
                {
                    string outputPath = Path.GetFullPath(options.ExtractVolumePath);
                    string outputDir = Path.GetDirectoryName(outputPath);
                    if (!string.IsNullOrWhiteSpace(outputDir))
                        Directory.CreateDirectory(outputDir);

                    ExtractVolume(stream, target, outputPath);
                }
                Console.WriteLine();
            }
        }

        static PartitionCandidate ResolveVolumeTarget(MountOptions options, List<PartitionCandidate> discovered, long streamLength)
        {
            if (options.VolumeOffset >= 0)
            {
                if (options.VolumeOffset >= streamLength)
                    throw new CommandLineUsageException("--volume-offset is outside the image.");

                long size = options.VolumeLength > 0 ? options.VolumeLength : (streamLength - options.VolumeOffset);
                if (size < 0)
                    size = 0;

                return new PartitionCandidate
                {
                    Index = 1,
                    Key = "custom-volume",
                    Name = "Custom Volume",
                    Offset = options.VolumeOffset,
                    Size = size,
                    IsRecovered = false
                };
            }

            if (!string.IsNullOrWhiteSpace(options.PartitionSelector))
                return ResolvePartitionSelector(options.PartitionSelector, discovered);

            if (discovered != null && discovered.Count > 0)
                return ChooseDefaultPartition(discovered);

            return null;
        }

        static void PrintVolumeStats(Stream stream, PartitionCandidate target, MountFeatureOptions features)
        {
            FatxRecoveryPartitionContext context;
            if (!FatxRecoveryPartitionContext.TryCreate(stream, target, features, out context))
            {
                Console.WriteLine("  FATX stats: unavailable (target range is not recognized as FATX).");
                return;
            }

            long maxClusters = context.MaxScannableClusters;
            long freeClusters = 0;
            for (uint cluster = 1; cluster <= maxClusters; cluster++)
                if (context.ChainMap[cluster] == FatxFileSystem.kClusterFree)
                    freeClusters++;

            long usedClusters = Math.Max(0, maxClusters - freeClusters);
            long totalBytes = maxClusters * context.ClusterSize;
            long freeBytes = freeClusters * context.ClusterSize;
            long usedBytes = usedClusters * context.ClusterSize;

            Console.WriteLine("  FATX stats:");
            Console.WriteLine("    Cluster size: {0:N0} bytes", context.ClusterSize);
            Console.WriteLine("    Total space:  {0:N2} GiB", totalBytes / 1024.0 / 1024.0 / 1024.0);
            Console.WriteLine("    Used space:   {0:N2} GiB", usedBytes / 1024.0 / 1024.0 / 1024.0);
            Console.WriteLine("    Free space:   {0:N2} GiB", freeBytes / 1024.0 / 1024.0 / 1024.0);
        }

        static void ExtractVolume(Stream stream, PartitionCandidate target, string outputPath)
        {
            Console.WriteLine("  Extracting volume to: {0}", outputPath);
            const int BufferSize = 8 * 1024 * 1024;
            byte[] buffer = new byte[BufferSize];

            stream.Position = target.Offset;
            long remaining = target.Size;
            long copied = 0;
            using (var output = new FileStream(outputPath, FileMode.Create, FileAccess.Write, FileShare.None, BufferSize, FileOptions.SequentialScan))
            {
                while (remaining > 0)
                {
                    int toRead = (int)Math.Min(BufferSize, remaining);
                    int read = stream.Read(buffer, 0, toRead);
                    if (read <= 0)
                        throw new IOException("Unexpected end-of-stream while extracting volume.");
                    output.Write(buffer, 0, read);
                    remaining -= read;
                    copied += read;

                    if ((copied % (512L * 1024 * 1024)) == 0 || remaining == 0)
                    {
                        double pct = target.Size == 0 ? 100.0 : (100.0 * copied / target.Size);
                        Console.WriteLine("    Extract progress: {0:N1}% ({1:N0}/{2:N0} bytes)", pct, copied, target.Size);
                    }
                }
            }

            Console.WriteLine("  Extract complete: {0:N0} bytes", target.Size);
        }

        static Assembly ResolveWinFspAssembly(object sender, ResolveEventArgs args)
        {
            AssemblyName requested;
            try
            {
                requested = new AssemblyName(args.Name);
            }
            catch
            {
                return null;
            }

            if (!string.Equals(requested.Name, "winfsp-msil", StringComparison.OrdinalIgnoreCase))
                return null;

            string installedMsil = FindInstalledWinFspMsilPath();
            if (string.IsNullOrWhiteSpace(installedMsil))
                return null;

            try
            {
                return Assembly.LoadFrom(installedMsil);
            }
            catch
            {
                return null;
            }
        }

        static void PrepareWinFspRuntime(string debugLogFile)
        {
            PreflightWinFspRuntime();
            ConfigureWinFspDebugLog(debugLogFile);
        }

        static void PreflightWinFspRuntime()
        {
            string appLocalMsil = GetAppLocalWinFspMsilPath();
            string installedMsil = FindInstalledWinFspMsilPath();

            if (string.IsNullOrWhiteSpace(installedMsil))
            {
                throw new WinFspRuntimeException(
                    "WinFsp runtime was not found. Install or repair WinFsp 2.x, then run Xtaf again. " +
                    "Xtaf loads WinFsp's installed winfsp-msil.dll so it matches the installed driver. " +
                    DescribeWinFspInteropState());
            }

            if (File.Exists(appLocalMsil) && WinFspMsilMajorMinorDiffer(appLocalMsil, installedMsil))
            {
                throw new WinFspRuntimeException(
                    "WinFsp DLL version mismatch before mount. Remove app-local winfsp-msil.dll from the Xtaf build/release folder, or rebuild so Xtaf loads the WinFsp-installed MSIL. " +
                    DescribeWinFspInteropState());
            }
        }

        static void ConfigureWinFspDebugLog(string debugLogFile)
        {
            if (string.IsNullOrEmpty(debugLogFile))
                return;

            try
            {
                if (FileSystemHost.SetDebugLogFile(debugLogFile) < 0)
                    throw new CommandLineUsageException("Could not open debug log file.");
            }
            catch (CommandLineUsageException)
            {
                throw;
            }
            catch (Exception ex)
            {
                string message;
                if (TryFormatWinFspInteropError(ex, out message))
                    throw new WinFspRuntimeException(message, ex);
                throw;
            }
        }

        static bool TryFormatWinFspInteropError(Exception ex, out string message)
        {
            Exception cause = FindWinFspInteropCause(ex);
            if (cause == null)
            {
                message = null;
                return false;
            }

            if (cause is TypeLoadException && ContainsIgnoreCase(cause.Message, "incorrect dll version"))
            {
                message = "WinFsp DLL version mismatch: " + cause.Message +
                    ". Use the winfsp-msil.dll installed with WinFsp; remove app-local copies from the Xtaf build/release folder. " +
                    DescribeWinFspInteropState();
                return true;
            }

            if (cause is DllNotFoundException)
            {
                message = "WinFsp native runtime could not be loaded: " + cause.Message +
                    ". Install or repair WinFsp. " + DescribeWinFspInteropState();
                return true;
            }

            if (cause is EntryPointNotFoundException)
            {
                message = "WinFsp native runtime is missing an expected entry point: " + cause.Message +
                    ". Install or repair the matching WinFsp runtime and MSIL files. " + DescribeWinFspInteropState();
                return true;
            }

            if (cause is FileLoadException && ContainsIgnoreCase(cause.Message, "manifest definition does not match"))
            {
                message = "WinFsp .NET interop assembly version mismatch: " + cause.Message +
                    ". Use the winfsp-msil.dll installed with WinFsp; remove app-local copies from the Xtaf build/release folder. " +
                    DescribeWinFspInteropState();
                return true;
            }

            message = "WinFsp .NET interop assembly could not be loaded: " + cause.Message +
                ". Install or repair WinFsp, then rebuild/run Xtaf with the matching installed MSIL. " +
                DescribeWinFspInteropState();
            return true;
        }

        static Exception FindWinFspInteropCause(Exception ex)
        {
            for (Exception current = ex; current != null; current = current.InnerException)
            {
                string text = current.Message ?? string.Empty;
                if (current is TypeLoadException && ContainsIgnoreCase(text, "incorrect dll version"))
                    return current;
                if (current is DllNotFoundException && ContainsIgnoreCase(text, "winfsp"))
                    return current;
                if (current is EntryPointNotFoundException && ContainsIgnoreCase(text, "Fsp"))
                    return current;
                if ((current is FileNotFoundException || current is FileLoadException) && ContainsIgnoreCase(text, "winfsp-msil"))
                    return current;
                if (current is TypeInitializationException && ContainsIgnoreCase(text, "Fsp.Interop.Api") && current.InnerException == null)
                    return current;
            }

            return null;
        }

        static bool ContainsIgnoreCase(string value, string search)
        {
            return value != null && value.IndexOf(search, StringComparison.OrdinalIgnoreCase) >= 0;
        }

        static bool WinFspMsilMajorMinorDiffer(string leftPath, string rightPath)
        {
            try
            {
                FileVersionInfo left = FileVersionInfo.GetVersionInfo(leftPath);
                FileVersionInfo right = FileVersionInfo.GetVersionInfo(rightPath);
                return left.FileMajorPart != right.FileMajorPart || left.FileMinorPart != right.FileMinorPart;
            }
            catch
            {
                return false;
            }
        }

        static string DescribeWinFspInteropState()
        {
            return "App-local winfsp-msil: " + DescribeWinFspMsilFile(GetAppLocalWinFspMsilPath()) +
                "; installed winfsp-msil: " + DescribeWinFspMsilFile(FindInstalledWinFspMsilPath()) + ".";
        }

        static string DescribeWinFspMsilFile(string path)
        {
            if (string.IsNullOrWhiteSpace(path) || !File.Exists(path))
                return "not found";

            try
            {
                FileVersionInfo version = FileVersionInfo.GetVersionInfo(path);
                AssemblyName assemblyName = AssemblyName.GetAssemblyName(path);
                return path + " (file " + version.FileVersion + ", assembly " + assemblyName.Version + ")";
            }
            catch
            {
                return path;
            }
        }

        static string GetAppLocalWinFspMsilPath()
        {
            return Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "winfsp-msil.dll");
        }

        static string FindInstalledWinFspMsilPath()
        {
            var candidates = new List<string>();

            foreach (string installDir in GetWinFspInstallDirectories())
            {
                AddWinFspMsilCandidate(candidates, Path.Combine(Path.Combine(installDir, "bin"), "winfsp-msil.dll"));
                AddWinFspMsilCandidate(candidates, Path.Combine(installDir, "winfsp-msil.dll"));
                AddWinFspSxsMsilCandidates(candidates, Path.Combine(installDir, "SxS"));
            }

            foreach (string sxsDir in GetWinFspSxsDirectories())
                AddWinFspSxsMsilCandidates(candidates, sxsDir);

            foreach (string candidate in candidates)
            {
                if (File.Exists(candidate))
                    return candidate;
            }

            return null;
        }

        static IEnumerable<string> GetWinFspInstallDirectories()
        {
            var directories = new List<string>();

            AddWinFspInstallDirectory(directories, Registry.GetValue(@"HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\WinFsp", "InstallDir", null) as string);
            AddWinFspInstallDirectory(directories, Registry.GetValue(@"HKEY_LOCAL_MACHINE\SOFTWARE\WinFsp", "InstallDir", null) as string);

            AddWinFspInstallDirectory(directories, Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ProgramFilesX86), "WinFsp"));
            AddWinFspInstallDirectory(directories, Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.ProgramFiles), "WinFsp"));
            AddWinFspInstallDirectory(directories, Path.Combine(Environment.GetEnvironmentVariable("ProgramW6432") ?? string.Empty, "WinFsp"));
            AddWinFspInstallDirectory(directories, Path.Combine(Environment.GetEnvironmentVariable("ProgramFiles") ?? string.Empty, "WinFsp"));

            return directories;
        }

        static IEnumerable<string> GetWinFspSxsDirectories()
        {
            var directories = new List<string>();

            AddWinFspInstallDirectory(directories, Registry.GetValue(@"HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\WinFsp", "SxsDir", null) as string);
            AddWinFspInstallDirectory(directories, Registry.GetValue(@"HKEY_LOCAL_MACHINE\SOFTWARE\WinFsp", "SxsDir", null) as string);

            return directories;
        }

        static void AddWinFspSxsMsilCandidates(List<string> candidates, string sxsDir)
        {
            if (string.IsNullOrWhiteSpace(sxsDir) || !Directory.Exists(sxsDir))
                return;

            AddWinFspMsilCandidate(candidates, Path.Combine(Path.Combine(sxsDir, "bin"), "winfsp-msil.dll"));
            AddWinFspMsilCandidate(candidates, Path.Combine(sxsDir, "winfsp-msil.dll"));

            string[] children;
            try
            {
                children = Directory.GetDirectories(sxsDir, "sxs.*");
            }
            catch
            {
                return;
            }

            Array.Sort(children, StringComparer.OrdinalIgnoreCase);
            for (int i = children.Length - 1; i >= 0; i--)
            {
                AddWinFspMsilCandidate(candidates, Path.Combine(Path.Combine(children[i], "bin"), "winfsp-msil.dll"));
                AddWinFspMsilCandidate(candidates, Path.Combine(children[i], "winfsp-msil.dll"));
            }
        }

        static void AddWinFspMsilCandidate(List<string> candidates, string path)
        {
            if (string.IsNullOrWhiteSpace(path))
                return;

            string fullPath = Path.GetFullPath(path);
            if (!candidates.Any(existing => string.Equals(existing, fullPath, StringComparison.OrdinalIgnoreCase)))
                candidates.Add(fullPath);
        }

        static void AddWinFspInstallDirectory(List<string> directories, string path)
        {
            if (string.IsNullOrWhiteSpace(path) || !Directory.Exists(path))
                return;

            string fullPath = Path.GetFullPath(path);
            if (!directories.Any(existing => string.Equals(existing, fullPath, StringComparison.OrdinalIgnoreCase)))
                directories.Add(fullPath);
        }

        static MountSession Mount(MountOptions options)
        {
            Stream stream = OpenImageStream(options.ImagePath, options.Features);
            var session = new MountSession(stream);

            try
            {
                if (options.VolumeOffset >= 0)
                {
                    long maxLength = Math.Max(0, stream.Length - options.VolumeOffset);
                    long size = options.VolumeLength > 0 ? Math.Min(options.VolumeLength, maxLength) : maxLength;
                    var custom = new PartitionCandidate
                    {
                        Index = 1,
                        Key = "custom-volume",
                        Name = "Custom Volume",
                        Offset = options.VolumeOffset,
                        Size = size,
                        IsRecovered = false
                    };

                    string failureReason;
                    TryMountPartition(session, options, custom, ResolveSingleMountPoint(options), new object(), false, out failureReason);
                    return session;
                }

                if (options.MountAllPartitions)
                {
                    List<PartitionCandidate> partitions = DiscoverPartitions(stream, options.Features);
                    if (partitions.Count == 0)
                        throw new IOException("No FATX partitions were discovered.");

                    if (string.IsNullOrWhiteSpace(options.MountRoot) && !string.Equals(options.MountPoint, "*", StringComparison.Ordinal))
                        throw new CommandLineUsageException("Use -m * or --mount-root when mounting all partitions.");

                    MountAllDiscoveredPartitions(session, options, partitions, TryMountPartition);

                    if (session.Volumes.Count == 0)
                        throw new IOException(BuildNoPartitionsMountedMessage(session));

                    return session;
                }

                if (!string.IsNullOrWhiteSpace(options.PartitionSelector))
                {
                    List<PartitionCandidate> partitions = DiscoverPartitions(stream, options.Features);
                    if (partitions.Count == 0)
                        throw new IOException("No FATX partitions were discovered.");

                    PartitionCandidate selected = ResolvePartitionSelector(options.PartitionSelector, partitions);
                    if (selected == null)
                        throw new CommandLineUsageException("Partition not found. Use --list-partitions.");

                    string failureReason;
                    TryMountPartition(session, options, selected, ResolveSingleMountPoint(options), new object(), false, out failureReason);
                    return session;
                }

                string fsType;
                FileSystemHost host = TryMountDirect(stream, options.ImagePath, ResolveSingleMountPoint(options), options.DebugFlags, options.Features, out fsType);
                if (host != null)
                {
                    session.Add(host, fsType, fsType);
                    return session;
                }

                List<PartitionCandidate> fallback = DiscoverPartitions(stream, options.Features);
                if (fallback.Count > 0)
                {
                    PartitionCandidate selected = ChooseDefaultPartition(fallback);
                    string failureReason;
                    TryMountPartition(session, options, selected, ResolveSingleMountPoint(options), new object(), false, out failureReason);
                    return session;
                }

                throw new IOException("Unsupported or invalid Xbox image format.");
            }
            catch
            {
                session.Dispose();
                throw;
            }
        }

        static Stream OpenImageStream(string imagePath, MountFeatureOptions features)
        {
            FileOptions openFlags = FileOptions.RandomAccess;
            if (features.DisableDiskCache)
                openFlags |= FileOptions.WriteThrough; // best-effort cache reduction

            return new FileStream(imagePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite, 1024 * 1024, openFlags);
        }

        static FileSystemHost TryMountDirect(
            Stream stream,
            string imagePath,
            string mountPoint,
            uint debugFlags,
            MountFeatureOptions features,
            out string fsType)
        {
            fsType = null;

            FileSystemHost host = TryMountWithFactory(stream, imagePath, mountPoint, debugFlags, delegate(Stream s, string p)
            {
                return new GdfxFileSystem(s, p, features);
            });
            if (host != null)
            {
                fsType = "GDFX";
                return host;
            }

            host = TryMountWithFactory(stream, imagePath, mountPoint, debugFlags, delegate(Stream s, string p)
            {
                return new StfsFileSystem(s, p, 0, features);
            });
            if (host != null)
            {
                fsType = "STFS";
                return host;
            }

            host = TryMountWithFactory(stream, imagePath, mountPoint, debugFlags, delegate(Stream s, string p)
            {
                return new FatxFileSystem(s, p, 0, 0, features);
            });
            if (host != null)
            {
                fsType = "FATX";
                return host;
            }

            return null;
        }

        static FileSystemHost TryMountWithFactory(
            Stream stream,
            string imagePath,
            string mountPoint,
            uint debugFlags,
            Func<Stream, string, ReadOnlyFileSystem> factory)
        {
            stream.Position = 0;
            FileSystemHost host = null;
            try
            {
                host = new FileSystemHost(factory(stream, imagePath));
                if (host.Mount(mountPoint, null, true, debugFlags) < 0)
                {
                    DisposeHost(host);
                    return null;
                }
                return host;
            }
            catch
            {
                if (host != null)
                    DisposeHost(host);
                throw;
            }
        }

        internal static void DisposeHost(FileSystemHost host)
        {
            if (host == null)
                return;

            try { host.Dispose(); }
            catch
            {
                try { host.Unmount(); } catch { }
            }
        }

        internal static int MountAllDiscoveredPartitions(
            MountSession session,
            MountOptions options,
            List<PartitionCandidate> partitions,
            PartitionMountAttempt mountPartition)
        {
            if (session == null)
                throw new ArgumentNullException("session");
            if (options == null)
                throw new ArgumentNullException("options");
            if (partitions == null)
                throw new ArgumentNullException("partitions");
            if (mountPartition == null)
                throw new ArgumentNullException("mountPartition");

            int mounted = 0;
            object streamLock = new object();
            foreach (PartitionCandidate partition in partitions)
            {
                string mountPoint;
                try
                {
                    mountPoint = ResolvePartitionMountPoint(options, partition);
                }
                catch (Exception ex)
                {
                    session.AddSkippedPartition(partition, "mount point failed: " + ex.Message);
                    continue;
                }

                string failureReason;
                if (mountPartition(session, options, partition, mountPoint, streamLock, true, out failureReason))
                {
                    mounted++;
                    continue;
                }

                session.AddSkippedPartition(partition, failureReason);
            }

            return mounted;
        }

        static bool TryMountPartition(
            MountSession session,
            MountOptions options,
            PartitionCandidate partition,
            string mountPoint,
            object streamLock,
            bool continueOnFailure,
            out string failureReason)
        {
            failureReason = null;
            FileSystemHost host = null;
            try
            {
                host = TryMountWithFactory(
                    session.Stream,
                    options.ImagePath,
                    mountPoint,
                    options.DebugFlags,
                    delegate(Stream stream, string path)
                    {
                        var fatx = new FatxFileSystem(stream, path, partition.Offset, partition.Size, options.Features);
                        fatx.StreamLock = streamLock;
                        return fatx;
                    });
            }
            catch (Exception ex)
            {
                failureReason = "mount failed: " + ex.Message;
                if (continueOnFailure)
                    return false;

                throw new IOException(BuildPartitionMountFailureMessage(partition), ex);
            }

            if (host == null)
            {
                failureReason = "mount failed";
                if (continueOnFailure)
                    return false;
                throw new IOException(BuildPartitionMountFailureMessage(partition));
            }

            session.Add(host, "FATX", string.Format("{0} (0x{1:X})", partition.Name, partition.Offset));
            return true;
        }

        static string BuildPartitionMountFailureMessage(PartitionCandidate partition)
        {
            return string.Format("Failed to mount partition '{0}' at 0x{1:X}.", partition.Name, partition.Offset);
        }

        static string BuildNoPartitionsMountedMessage(MountSession session)
        {
            if (session == null || session.SkippedPartitions.Count == 0)
                return "No partitions could be mounted.";

            return "No partitions could be mounted. Skipped partitions: " + FormatSkippedPartitionsInline(session.SkippedPartitions) + ".";
        }

        static string FormatSkippedPartitionsInline(IList<SkippedPartitionInfo> skippedPartitions)
        {
            var parts = new List<string>();
            foreach (SkippedPartitionInfo skipped in skippedPartitions)
                parts.Add(string.Format("{0} at 0x{1:X} ({2})", skipped.Name, skipped.Offset, skipped.Reason));
            return string.Join("; ", parts.ToArray());
        }

        static List<PartitionCandidate> DiscoverPartitions(Stream stream, MountFeatureOptions features)
        {
            var discovered = new List<PartitionCandidate>();
            var seenOffsets = new HashSet<long>();

            foreach (PartitionProfileEntry profile in KnownPartitions)
            {
                FAT_VOLUME_METADATA header;
                if (!TryReadFatxHeader(stream, profile.Offset, out header))
                    continue;
                if (!seenOffsets.Add(profile.Offset))
                    continue;

                discovered.Add(new PartitionCandidate
                {
                    Key = profile.Key,
                    Name = profile.Name,
                    Offset = profile.Offset,
                    Size = profile.Size,
                    IsRecovered = false
                });
            }

            if ((features.RestorePartitionTable || features.RecoveryMode) && discovered.Count < MaxRecoveredPartitions)
            {
                int recovered = 0;
                for (long offset = 0; offset + FatxFileSystem.kSectorSize <= stream.Length; offset += AutoScanStep)
                {
                    if (seenOffsets.Contains(offset))
                        continue;

                    FAT_VOLUME_METADATA header;
                    if (!TryReadFatxHeader(stream, offset, out header))
                        continue;

                    seenOffsets.Add(offset);
                    recovered++;
                    discovered.Add(new PartitionCandidate
                    {
                        Key = string.Format("recovered-{0}", recovered),
                        Name = string.Format("Recovered FATX {0}", recovered),
                        Offset = offset,
                        Size = 0,
                        IsRecovered = true
                    });

                    if (discovered.Count >= MaxRecoveredPartitions)
                        break;
                }
            }

            discovered = discovered.OrderBy(x => x.Offset).ToList();
            FinalizePartitionSizes(discovered, stream.Length, features);
            for (int i = 0; i < discovered.Count; i++)
                discovered[i].Index = i + 1;

            return discovered;
        }

        static void FinalizePartitionSizes(List<PartitionCandidate> partitions, long imageLength, MountFeatureOptions features)
        {
            for (int i = 0; i < partitions.Count; i++)
            {
                PartitionCandidate current = partitions[i];
                long size = current.Size;
                bool useAnyNextOffset = size <= 0 ||
                    current.IsRecovered ||
                    (features.FTakesAllOverride && IsDynamicContentPartition(current.Key));

                long nextOffset = imageLength;
                for (int y = i + 1; y < partitions.Count; y++)
                {
                    if (partitions[y].Offset > current.Offset && (useAnyNextOffset || !partitions[y].IsRecovered))
                    {
                        nextOffset = partitions[y].Offset;
                        break;
                    }
                }

                long maxSize = nextOffset - current.Offset;
                long imageAvailable = imageLength - current.Offset;
                if (maxSize < 0 || maxSize > imageAvailable)
                    maxSize = imageAvailable;
                if (maxSize < 0)
                    maxSize = 0;

                if (useAnyNextOffset || size > maxSize)
                    size = maxSize;

                if (size < 0)
                    size = 0;
                current.Size = size;
            }
        }

        static bool TryReadFatxHeader(Stream stream, long offset, out FAT_VOLUME_METADATA header)
        {
            header = default(FAT_VOLUME_METADATA);
            if (offset < 0 || offset + FatxFileSystem.kSectorSize > stream.Length)
                return false;

            try
            {
                stream.Position = offset;
                header = stream.ReadStruct<FAT_VOLUME_METADATA>();
                return header.IsValid;
            }
            catch
            {
                return false;
            }
        }

        static bool IsDynamicContentPartition(string key)
        {
            if (string.IsNullOrWhiteSpace(key))
                return false;
            string lower = key.ToLowerInvariant();
            return lower == "content" || lower == "mucontent";
        }

        static PartitionCandidate ResolvePartitionSelector(string selector, List<PartitionCandidate> partitions)
        {
            if (string.IsNullOrWhiteSpace(selector))
                return null;

            int index;
            if (int.TryParse(selector, out index))
                return partitions.FirstOrDefault(x => x.Index == index);

            string key = NormalizePartitionSelector(selector);
            PartitionCandidate exact = partitions.FirstOrDefault(x => string.Equals(x.Key, key, StringComparison.OrdinalIgnoreCase));
            if (exact != null)
                return exact;

            string noSpace = RemoveWhitespace(selector);
            exact = partitions.FirstOrDefault(x => string.Equals(RemoveWhitespace(x.Name), noSpace, StringComparison.OrdinalIgnoreCase));
            if (exact != null)
                return exact;

            return partitions.FirstOrDefault(x =>
                x.Key.IndexOf(key, StringComparison.OrdinalIgnoreCase) >= 0 ||
                x.Name.IndexOf(selector, StringComparison.OrdinalIgnoreCase) >= 0);
        }

        static string NormalizePartitionSelector(string selector)
        {
            string normalized = RemoveWhitespace(selector).ToLowerInvariant();
            switch (normalized)
            {
                case "cache": return "cache0";
                case "recovery":
                case "recoverypartition": return "recovery";
                case "backcompat":
                case "compatibility":
                case "backwardcompatibility":
                case "xbc":
                case "xbox1": return "backcompat";
                case "systemextended":
                case "systemext": return "systemext";
                case "system":
                case "systempartition": return "systempartition";
                case "systemauxiliary":
                case "systemaux": return "systemaux";
                case "data": return "content";
                default: return normalized;
            }
        }

        static PartitionCandidate ChooseDefaultPartition(List<PartitionCandidate> partitions)
        {
            foreach (string key in DefaultPriority)
            {
                PartitionCandidate match = partitions.FirstOrDefault(x => string.Equals(x.Key, key, StringComparison.OrdinalIgnoreCase));
                if (match != null)
                    return match;
            }

            return partitions.OrderByDescending(x => x.Size).First();
        }

        static string ResolveSingleMountPoint(MountOptions options)
        {
            if (string.IsNullOrWhiteSpace(options.MountPoint))
                throw new CommandLineUsageException("Mount point is required.");
            return ResolveWinFspMountPoint(options.MountPoint, Utility.IsAdministrator());
        }

        static string ResolvePartitionMountPoint(MountOptions options, PartitionCandidate partition)
        {
            if (!string.IsNullOrWhiteSpace(options.MountRoot))
            {
                Directory.CreateDirectory(options.MountRoot);
                string folder = string.Format("{0:D2}_{1}", partition.Index, SanitizePath(partition.Key));
                string mountPath = Path.Combine(options.MountRoot, folder);
                if (Directory.Exists(mountPath))
                {
                    if (Directory.EnumerateFileSystemEntries(mountPath).Any())
                        throw new IOException("Mount path is not empty: " + mountPath);
                    Directory.Delete(mountPath);
                }
                return mountPath;
            }

            return ResolveWinFspMountPoint(options.MountPoint, Utility.IsAdministrator());
        }

        static string ResolveWinFspMountPoint(string mountPoint, bool isAdministrator)
        {
            if (mountPoint == "*")
                return isAdministrator ? ResolveAvailableGlobalDriveMountPoint() : null;

            char driveLetter;
            if (isAdministrator && IsDriveLetterMountPoint(mountPoint, out driveLetter))
                return ToWinFspGlobalDriveMountPoint(driveLetter);

            return mountPoint;
        }

        static string ResolveAvailableGlobalDriveMountPoint()
        {
            for (char driveLetter = 'Z'; driveLetter >= 'D'; driveLetter--)
            {
                if (!Directory.Exists(driveLetter + @":\"))
                    return ToWinFspGlobalDriveMountPoint(driveLetter);
            }

            throw new IOException("Out of drive letters.");
        }

        static bool IsDriveLetterMountPoint(string mountPoint, out char driveLetter)
        {
            driveLetter = '\0';
            if (string.IsNullOrWhiteSpace(mountPoint))
                return false;
            if (mountPoint.Length != 2 && mountPoint.Length != 3)
                return false;
            if (!char.IsLetter(mountPoint[0]) || mountPoint[1] != ':')
                return false;
            if (mountPoint.Length == 3 && mountPoint[2] != '\\' && mountPoint[2] != '/')
                return false;

            driveLetter = char.ToUpperInvariant(mountPoint[0]);
            return true;
        }

        static string ToWinFspGlobalDriveMountPoint(char driveLetter)
        {
            return @"\\.\" + char.ToUpperInvariant(driveLetter) + ":";
        }

        static string SanitizePath(string value)
        {
            if (string.IsNullOrWhiteSpace(value))
                return "partition";
            char[] invalid = Path.GetInvalidFileNameChars();
            char[] chars = value.ToCharArray();
            for (int i = 0; i < chars.Length; i++)
                if (invalid.Contains(chars[i]))
                    chars[i] = '_';
            return new string(chars);
        }

        static string RemoveWhitespace(string value)
        {
            if (string.IsNullOrWhiteSpace(value))
                return string.Empty;

            var chars = new List<char>(value.Length);
            foreach (char c in value)
                if (!char.IsWhiteSpace(c))
                    chars.Add(c);
            return new string(chars.ToArray());
        }

        static void PrintPartitions(List<PartitionCandidate> partitions, string imagePath)
        {
            Console.WriteLine();
            Console.WriteLine("Image: {0}", imagePath);
            if (partitions.Count == 0)
            {
                Console.WriteLine("No FATX partitions were discovered.");
                Console.WriteLine();
                return;
            }

            Console.WriteLine("Discovered FATX partitions:");
            Console.WriteLine("Idx  Key             Name                          Offset        Size");
            foreach (PartitionCandidate partition in partitions)
            {
                Console.WriteLine(
                    "{0,3}  {1,-14}  {2,-28}  0x{3:X10}  0x{4:X10}{5}",
                    partition.Index,
                    partition.Key,
                    partition.Name,
                    partition.Offset,
                    partition.Size,
                    partition.IsRecovered ? "  (recovered)" : "");
            }
            Console.WriteLine();
        }

        static void PrintDiskpartAssist(string imagePath, List<PartitionCandidate> partitions)
        {
            Console.WriteLine("Diskpart-style assistant:");
            Console.WriteLine("  1) Inspect partitions");
            Console.WriteLine("     {0} -i \"{1}\" --list-partitions", ProgramName, imagePath);
            Console.WriteLine("  2) Mount one partition");
            Console.WriteLine("     {0} -i \"{1}\" --partition content -m X:", ProgramName, imagePath);
            Console.WriteLine("  3) Mount all partitions (auto drives)");
            Console.WriteLine("     {0} -i \"{1}\" --all-partitions -m *", ProgramName, imagePath);
            Console.WriteLine("  4) Mount all partitions to a folder root");
            Console.WriteLine("     {0} -i \"{1}\" --all-partitions --mount-root \"C:\\mount\\xbox360\"", ProgramName, imagePath);
            Console.WriteLine("  5) Recovery workflow (metadata + deleted + carve)");
            Console.WriteLine("     {0} -i \"{1}\" --partition content --metadata-scan --recover-deleted --carve-files --carve-deep", ProgramName, imagePath);
            Console.WriteLine("  6) Audit image bloat / trailing zero padding");
            Console.WriteLine("     {0} -i \"{1}\" --analyze-image-size", ProgramName, imagePath);
            Console.WriteLine("  7) Trim trailing zeros into a smaller image");
            Console.WriteLine("     {0} -i \"{1}\" --analyze-image-size --trim-image \"D:\\images\\trimmed.img\"", ProgramName, imagePath);
            Console.WriteLine("  8) Read FATX stats from a custom volume range");
            Console.WriteLine("     {0} -i \"{1}\" --volume-offset 0x2D0EB0000 --volume-length 0x181DAC6000 --volume-stats", ProgramName, imagePath);
            if (partitions.Count > 0)
            {
                PartitionCandidate suggested = ChooseDefaultPartition(partitions);
                Console.WriteLine("Suggested default partition: {0} (index {1})", suggested.Name, suggested.Index);
            }
            Console.WriteLine();
        }

        static void PrintMounts(string imagePath, MountSession session)
        {
            Console.WriteLine();
            Console.WriteLine("Image: {0}", imagePath);
            Console.WriteLine("Mounted volumes: {0}", session.Volumes.Count);
            foreach (MountedVolumeInfo volume in session.Volumes)
                Console.WriteLine("  {0}: {1} -> {2}", volume.FileSystemType, volume.LogicalName, volume.MountPoint);
            if (session.SkippedPartitions.Count > 0)
            {
                Console.WriteLine("Skipped partitions: {0}", session.SkippedPartitions.Count);
                foreach (SkippedPartitionInfo skipped in session.SkippedPartitions)
                    Console.WriteLine("  {0} at 0x{1:X}: {2}", skipped.Name, skipped.Offset, skipped.Reason);
            }
            Console.WriteLine();
            Console.WriteLine("Press CTRL+C to unmount.");
            Console.WriteLine();
        }

        static void WaitForCtrlC()
        {
            using (var waitHandle = new ManualResetEvent(false))
            {
                ConsoleCancelEventHandler handler = delegate(object sender, ConsoleCancelEventArgs e)
                {
                    e.Cancel = true;
                    waitHandle.Set();
                };

                Console.CancelKeyPress += handler;
                try { waitHandle.WaitOne(); }
                finally { Console.CancelKeyPress -= handler; }
            }
        }

        static void PrintUsage()
        {
            Console.WriteLine(
                "Usage: {0} -i <ImagePath> [mount|recovery|size options]\n" +
                "\n" +
                "Core:\n" +
                "  -i <ImagePath>           Path to Xbox image.\n" +
                "  -m <MountPoint|*>        Mount point or wildcard drive assignment (mount flow).\n" +
                "                           Elevated drive-letter mounts are global for Explorer visibility.\n" +
                "  -d <DebugFlags>          WinFsp debug flags (-1 enables all logs).\n" +
                "  -D <LogFile>             WinFsp debug log file path.\n" +
                "\n" +
                "Partition Workflow:\n" +
                "  --list-partitions        List discovered FATX partitions.\n" +
                "  --partition <Name|Index> Mount one partition.\n" +
                "  --all-partitions         Mount all discovered partitions.\n" +
                "  --mount-root <Path>      Mount all partitions under a directory root.\n" +
                "  --diskpart               Show diskpart-style guidance.\n" +
                "\n" +
                "Advanced (FATXplorer-style):\n" +
                "  --read-only              Read-only mode (default).\n" +
                "  --recovery-mode          Recoverable parsing behavior.\n" +
                "  --f-takes-all-override   Content partition can take remaining image space.\n" +
                "  --disable-disk-cache     Best-effort write-through image open mode.\n" +
                "  --ignore-security-sector Full GDFX scan mode.\n" +
                "  --restore-partition-table Recover partitions by scanning image offsets.\n" +
                "\n" +
                "Recovery Workflow:\n" +
                "  --metadata-scan          Enumerate FATX directory metadata candidates.\n" +
                "  --metadata-scan-limit <N> Scan first N data bytes only (bytes, KiB, MiB, GiB).\n" +
                "  --recover-deleted        Recover deleted FATX entries using chain-aware recovery.\n" +
                "  --carve-files            Signature carve files from FATX data area.\n" +
                "  --carve-deep             Deep scan: scan all clusters, not only free clusters.\n" +
                "  --carve-interval <mode>  byte|align|sector|page|cluster.\n" +
                "  --recovery-output <Path> Output folder for recovery artifacts.\n" +
                "\n" +
                "Image Size Tools:\n" +
                "  --analyze-image-size     Scan image for zero-block/trailing-zero bloat.\n" +
                "  --trim-image <Path>      Write a trimmed copy up to last non-zero byte.\n" +
                "  --trim-block-mib <MiB>   Audit scan block size (default: 16).\n" +
                "\n" +
                "Custom Volume Tools:\n" +
                "  --volume-offset <Num>    Explicit volume offset (decimal or 0x hex).\n" +
                "  --volume-length <Num>    Explicit volume length (decimal or 0x hex).\n" +
                "  --volume-stats           Print FATX used/free stats for target volume.\n" +
                "  --extract-volume <Path>  Copy target volume range into a new image file.\n" +
                "\n" +
                "  -? --help /?             Show this help.\n",
                ProgramName);
        }
    }
}