chore: development v0.1.1 - comprehensive testing complete [auto-commit]

Author: githubrobbi

Cargo.lock

@@ -21,7 +21,7 @@ keywords.workspace = true
 categories.workspace = true
 
 [[bin]]
-name = "uffs-gui"
+name = "uffs_gui"
 path = "src/main.rs"
 
 [dependencies]

crates/uffs-gui/Cargo.toml

@@ -24,6 +24,10 @@ readme.workspace = true
 keywords.workspace = true
 categories.workspace = true
 
+[[bin]]
+name = "uffs_mft"
+path = "src/main.rs"
+
 [dependencies]
 # Internal: Polars facade
 uffs-polars.workspace = true
@@ -33,9 +37,21 @@ bitflags.workspace = true
 
 # Error handling
 thiserror.workspace = true
+anyhow.workspace = true
 rayon.workspace = true
 zstd = { version = "0.13.3", optional = true }
 
+# CLI (for uffs_mft binary)
+clap.workspace = true
+indicatif.workspace = true
+
+# Async runtime
+tokio.workspace = true
+
+# Logging
+tracing.workspace = true
+tracing-subscriber.workspace = true
+
 # Windows APIs (Windows only)
 [target.'cfg(windows)'.dependencies]
 windows.workspace = true

crates/uffs-mft/Cargo.toml

@@ -0,0 +1,185 @@
+//! # uffs_mft: MFT Command-Line Tool
+//!
+//! Low-level tool for reading and exporting NTFS Master File Table data.
+//!
+//! ## Usage
+//!
+//! ```bash
+//! # Read MFT from C: drive and export to Parquet
+//! uffs_mft read --drive C --output c_drive.parquet
+//!
+//! # Show MFT information for a drive
+//! uffs_mft info --drive C
+//!
+//! # List all NTFS drives
+//! uffs_mft drives
+//! ```
+//!
+//! **Note**: This tool requires Administrator privileges on Windows.
+
+use std::path::PathBuf;
+
+use anyhow::{Result, bail};
+use clap::{Parser, Subcommand};
+use tracing_subscriber::EnvFilter;
+
+#[cfg(windows)]
+use anyhow::Context;
+#[cfg(windows)]
+use indicatif::{ProgressBar, ProgressStyle};
+#[cfg(windows)]
+use tracing::info;
+#[cfg(windows)]
+use uffs_mft::MftReader;
+
+/// uffs_mft: Low-level NTFS MFT reading tool
+#[derive(Parser)]
+#[command(name = "uffs_mft")]
+#[command(author, version, about, long_about = None)]
+struct Cli {
+    /// Enable verbose output
+    #[arg(short, long, global = true)]
+    verbose: bool,
+
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Read MFT from a drive and export to Parquet
+    Read {
+        /// Drive letter (e.g., C, D, E)
+        #[arg(short, long)]
+        drive: char,
+
+        /// Output file path (Parquet format)
+        #[arg(short, long)]
+        output: PathBuf,
+    },
+
+    /// Show MFT information for a drive
+    Info {
+        /// Drive letter (e.g., C, D, E)
+        #[arg(short, long)]
+        drive: char,
+    },
+
+    /// List all available NTFS drives
+    Drives,
+}
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    // Initialize logging
+    let filter = if cli.verbose {
+        EnvFilter::new("debug")
+    } else {
+        EnvFilter::new("info")
+    };
+    tracing_subscriber::fmt().with_env_filter(filter).init();
+
+    // Check platform
+    #[cfg(not(windows))]
+    {
+        bail!(
+            "uffs_mft only works on Windows.\n\
+             It requires direct access to the NTFS Master File Table via Windows APIs."
+        );
+    }
+
+    #[cfg(windows)]
+    {
+        match cli.command {
+            Commands::Read { drive, output } => cmd_read(drive, output).await,
+            Commands::Info { drive } => cmd_info(drive).await,
+            Commands::Drives => cmd_drives().await,
+        }
+    }
+}
+
+#[cfg(windows)]
+async fn cmd_read(drive: char, output: PathBuf) -> Result<()> {
+    info!("Reading MFT from {}:", drive.to_ascii_uppercase());
+
+    let pb = ProgressBar::new_spinner();
+    pb.set_style(
+        ProgressStyle::default_spinner()
+            .template("{spinner:.green} {msg}")
+            .expect("valid template"),
+    );
+    pb.set_message("Opening volume...");
+
+    let reader = MftReader::open(drive)
+        .await
+        .with_context(|| format!("Failed to open drive {}:", drive))?;
+
+    pb.set_message("Reading MFT records...");
+    let df = reader
+        .read_all()
+        .await
+        .with_context(|| "Failed to read MFT")?;
+
+    pb.set_message("Saving to Parquet...");
+    MftReader::save_parquet(&df, &output).with_context(|| "Failed to save Parquet")?;
+
+    pb.finish_with_message(format!(
+        "✅ Exported {} records to {}",
+        df.height(),
+        output.display()
+    ));
+
+    Ok(())
+}
+
+#[cfg(windows)]
+async fn cmd_info(drive: char) -> Result<()> {
+    use uffs_mft::platform::VolumeHandle;
+
+    info!("MFT Info for {}:", drive.to_ascii_uppercase());
+
+    let handle = VolumeHandle::open(drive).with_context(|| format!("Failed to open {}:", drive))?;
+
+    let vol_data = handle
+        .get_ntfs_volume_data()
+        .with_context(|| "Failed to get volume data")?;
+
+    println!("Drive: {}:", drive.to_ascii_uppercase());
+    println!("  Bytes per sector:     {}", vol_data.bytes_per_sector);
+    println!("  Bytes per cluster:    {}", vol_data.bytes_per_cluster);
+    println!(
+        "  Bytes per MFT record: {}",
+        vol_data.bytes_per_file_record_segment
+    );
+    println!("  Total clusters:       {}", vol_data.total_clusters);
+    println!("  MFT start LCN:        {}", vol_data.mft_start_lcn);
+    println!("  MFT valid length:     {} bytes", vol_data.mft_valid_data_length);
+
+    let record_count = vol_data.mft_valid_data_length / vol_data.bytes_per_file_record_segment as u64;
+    println!("  Estimated records:    {record_count}");
+
+    Ok(())
+}
+
+#[cfg(windows)]
+async fn cmd_drives() -> Result<()> {
+    use uffs_mft::platform::detect_ntfs_drives;
+
+    info!("Detecting NTFS drives...");
+
+    let drives = detect_ntfs_drives();
+
+    if drives.is_empty() {
+        println!("No NTFS drives found.");
+    } else {
+        println!("NTFS drives:");
+        for drive in drives {
+            println!("  {}:", drive);
+        }
+    }
+
+    Ok(())
+}
+

crates/uffs-mft/src/main.rs

@@ -24,7 +24,7 @@ keywords.workspace = true
 categories.workspace = true
 
 [[bin]]
-name = "uffs-tui"
+name = "uffs_tui"
 path = "src/main.rs"
 
 [dependencies]

crates/uffs-tui/Cargo.toml

@@ -0,0 +1,68 @@
+# UFFS Binary Distribution
+
+This directory contains pre-built UFFS binaries.
+
+## ⚠️ Windows Only
+
+**UFFS is a Windows-only tool.** It reads the NTFS Master File Table (MFT)
+directly using Windows kernel APIs for ultra-fast file searching.
+
+macOS and Linux are only used as cross-compilation hosts - the resulting
+binaries still only run on Windows.
+
+## Binaries
+
+| Binary | Description |
+|--------|-------------|
+| `uffs` | Main CLI tool for fast file searching |
+| `uffs_mft` | Low-level MFT reading tool (read, info, drives) |
+| `uffs_tui` | Terminal UI for interactive searching |
+| `uffs_gui` | Graphical UI (placeholder) |
+
+## Structure
+
+- `latest/` - Symlink to the current version
+- `v{version}/{binary}/` - Binaries for each version
+  - `{binary}-windows-x64.exe` - Windows x64 (the only supported platform)
+
+## Installation
+
+### Windows
+
+Copy the binary to a directory in your PATH:
+
+```powershell
+copy uffs-windows-x64.exe C:\Users\YourName\bin\uffs.exe
+```
+
+Or add the bin directory to your PATH:
+
+```powershell
+# Add C:\Users\YourName\bin to your PATH if not already there
+$env:Path += ";$env:USERPROFILE\bin"
+```
+
+## Cross-Compilation
+
+To build Windows binaries from macOS or Linux:
+
+```bash
+# Install prerequisites
+cargo install cargo-xwin
+rustup target add x86_64-pc-windows-msvc
+
+# Build
+rust-script scripts/build-cross-all.rs
+```
+
+## Why Windows Only?
+
+UFFS achieves its speed by reading the NTFS Master File Table (MFT) directly
+from disk, bypassing the Windows file enumeration APIs. This requires:
+
+- Direct volume access via `\\.\X:` paths
+- Windows kernel ioctls like `FSCTL_GET_NTFS_VOLUME_DATA`
+- Administrator privileges for raw disk access
+
+These APIs are Windows-specific and cannot be replicated on other platforms.
+

dist/README.md

@@ -0,0 +1 @@
+v0.1.1

dist/latest

@@ -714,6 +714,71 @@ deploy-release:
     @printf "\033[0;34m📦 Deploying release binary...\033[0m\n"
     just copy-binary release
 
+# Install latest pre-built binaries from dist/ to ~/bin (platform-aware)
+# Install UFFS binaries to ~/bin (Windows only)
+# UFFS is Windows-only - it requires NTFS MFT access via Windows APIs
+# Binaries: uffs, uffs_mft, uffs_tui, uffs_gui
+use:
+    #!/usr/bin/env bash
+    printf "\033[0;34m📦 Installing latest UFFS binaries to ~/bin...\033[0m\n"
+    printf "\033[1;33mℹ️  Note: UFFS is Windows-only (requires NTFS MFT access)\033[0m\n"
+
+    # Detect platform
+    OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+    ARCH=$(uname -m)
+
+    case "$OS-$ARCH" in
+        mingw*|msys*|cygwin*)
+            PLATFORM="windows-x64"
+            ;;
+        darwin-arm64|darwin-x86_64|linux-x86_64|linux-aarch64)
+            printf "\033[0;31m❌ UFFS only runs on Windows.\033[0m\n"
+            printf "\033[0;34m   UFFS reads the NTFS Master File Table directly using Windows APIs.\033[0m\n"
+            printf "\033[0;34m   Use 'just go' to cross-compile Windows binaries from this host.\033[0m\n"
+            exit 1
+            ;;
+        *)
+            printf "\033[0;31m❌ Unsupported platform: $OS-$ARCH\033[0m\n"
+            exit 1
+            ;;
+    esac
+
+    printf "\033[0;34m  → Platform: $PLATFORM\033[0m\n"
+
+    # Create ~/bin if needed
+    mkdir -p ~/bin
+
+    # Binaries to install
+    BINARIES="uffs uffs_mft uffs_tui uffs_gui"
+    INSTALLED=0
+    SKIPPED=0
+
+    for BINARY in $BINARIES; do
+        SRC="dist/latest/$BINARY/$BINARY-$PLATFORM.exe"
+        DEST="$HOME/bin/$BINARY.exe"
+
+        if [[ -f "$SRC" ]]; then
+            cp "$SRC" "$DEST"
+            chmod +x "$DEST"
+            printf "\033[0;32m  ✅ $BINARY.exe\033[0m\n"
+            INSTALLED=$((INSTALLED + 1))
+        else
+            printf "\033[1;33m  ⚠️  $BINARY (not found for $PLATFORM)\033[0m\n"
+            SKIPPED=$((SKIPPED + 1))
+        fi
+    done
+
+    printf "\033[0;32m✅ Installed $INSTALLED binaries to ~/bin\033[0m\n"
+    if [[ $SKIPPED -gt 0 ]]; then
+        printf "\033[1;33m⚠️  Skipped $SKIPPED (run 'just go' to build all binaries)\033[0m\n"
+    fi
+
+    # PATH guidance
+    if ! echo "$PATH" | grep -q "$HOME/bin"; then
+        printf "\033[1;33m⚠️  ~/bin not in PATH. Add to your shell profile:\033[0m\n"
+        printf "   export PATH=\"\$HOME/bin:\$PATH\"\n"
+    fi
+
 # Git commit with auto-generated message
 commit:
     @printf "\033[0;34m📝 Creating auto-generated commit...\033[0m\n"