Skip to content
Andrew Paolucci edited this page Nov 19, 2026 · 5 revisions

robocopy2rust Project Wiki

Welcome to the official documentation hub for robocopy2rust — a 100% pure-Rust desktop GUI wrapper, bidirectional command/.rcj job orchestrator, streaming telemetry runner, air-gapped audit reporter, CLI, and Model Context Protocol (MCP) server for Microsoft Robocopy (robocopy.exe).


Core Design Goals

  1. Zero Heavy Runtimes: No Electron, no WebView2/Chromium, no Node.js, and no .NET Framework runtime.
  2. Maximum Windows Admin, VM & Server RDP Safety: Ships robocopy2rust-win32 on native WinSafe 0.0.29 Win32 Common Controls — requiring zero GPU/OpenGL hardware acceleration and zero external C/C++ UI runtimes when run elevated as Administrator or over Windows Server RDP.
  3. Full Cross-Platform Parity: Ships robocopy2rust-iced on Iced 0.14 (wgpu + tiny-skia CPU fallback) across Linux, macOS, and Windows (robocopy2rust gui --iced), so engineers can design, parse, validate, convert .rcj/.bat/.ps1/schtasks, and audit Robocopy logs identically on any OS.
  4. Safety by Default: Built-in /R:3 /W:5 retry defaults (avoiding Robocopy's 1,000,000 retry hang), CommandLineToArgvW-safe trailing-backslash quoting, pre-flight conflict validation, Dry-Run (/L) previews, and mandatory destructive confirmation guards across GUI, CLI, and MCP.

Comparison vs. Legacy Workflows

Capability robocopy2rust (WinSafe + Iced) Raw robocopy.exe Legacy GUIs (RoboGUI / ChoEazyCopy) Ad-hoc PowerShell Scripts
Windows Native & RDP Stability Authentic Win32 (winsafe) — zero GPU/OpenGL crash risk over RDP/VMs Console only .NET Framework / WinForms None
Cross-Platform Parity Unified Iced 0.14 UI on Linux, macOS, and Windows (tiny-skia CPU fallback) Windows only Windows only PowerShell only
Windows 10/11 Switches Full coverage (/IoMaxSize, /IoRate, /LFSM, /COMPRESS, /NOCLONE, /SPARSE) Manual flag recall Partial / dated switches Manual string concatenation
Quoting & Trailing \ Safety Automatic path normalization + CommandLineToArgvW backslash doubling Easy to break "C:\dir\" Basic quoting Error-prone string escaping
Bidirectional .rcj & CLI Parser Paste any command or import UTF-8/UTF-16 .rcj back into GUI Separate /JOB: syntax Export only or partial None
Destructive Safety Guards Dry-Run (/L) workflow & explicit /MIR / /PURGE / /MOVE / /MOV guard Immediate execution Basic prompt Manual -WhatIf
Live Telemetry & Reports Real-time \r progress, parsed file diff table, air-gapped HTML/JSON/MD Plain text scroll Raw text box Plain log file
AI Agent Integration Native stdio MCP Server (robocopy2rust-mcp, 9 tools) None None None

Shipped Binaries (Workspace v0.1.0)

Measured Windows x86_64 release binary outputs (cargo build --workspace --release with opt-level = 3, lto = "thin", strip = true):

Binary Role Platforms Release Size (Windows)
robocopy2rust (.exe) Unified CLI, job orchestrator, MCP subcommand, & default GUI launcher Windows, Linux, macOS 3,461,120 B (~3.30 MiB)
robocopy2rust-win32.exe Native zero-GPU Win32 Common Controls GUI via WinSafe 0.0.29 Windows (default GUI) 2,918,912 B (~2.78 MiB)
robocopy2rust-iced (.exe) Cross-platform Iced 0.14 desktop GUI (wgpu + tiny-skia fallback) Linux, macOS, Windows (--iced) 11,239,936 B (~10.72 MiB)
robocopy2rust-mcp (.exe) Standalone JSON-RPC 2.0 stdio Model Context Protocol (MCP) server Windows, Linux, macOS 2,797,056 B (~2.67 MiB)

Quick Start

# Launch the default GUI (robocopy2rust-win32 on Windows; robocopy2rust-iced on Linux/macOS)
robocopy2rust

# Launch the cross-platform Iced UI explicitly on Windows
robocopy2rust gui --iced

# Run a safe /L Dry-Run simulation and output an air-gapped HTML audit report
robocopy2rust dry-run --source "C:\Data Src\" --dest "D:\Backup" --report preview.html

# Parse an existing command line or .rcj job file into structured JSON
robocopy2rust parse job.rcj --rcj --json

# Decode Robocopy's 0..=16 bitmask exit code
robocopy2rust decode 3

# Start the stdio MCP server (9 structured tools)
robocopy2rust mcp

Wiki Directory

Getting Started & Architecture

  • Workspace Architecture — 7-crate dependency graph, RobocopyJob data model, Windows quoting engine, live streaming runner, and persistence store.
  • Building, Testing & CI/CD — Rust 1.88+ (2024 edition) toolchain setup, Linux/Windows/macOS dependencies, the 24-test suite (including real host robocopy.exe tests), GitHub Actions CI, cargo-deny, Release workflows, and packaging/ WinGet/Homebrew manifests.

Desktop GUIs, Decisions & Hardening

  • Dual-GUI Guide (Win32 & Iced) — Feature walkthrough, launcher behavior, ComCtl v6 manifest/resources, live console relay, batch queue, and Iced/WinSafe parity matrix.
  • GUI Framework Decision & Comparison — Architectural evolution from egui prototype to WinSafe + Iced, plus full evaluation against Slint, GPUI, Dioxus 0.7, Relm4, Winio, and Tauri v2.
  • Security & Stability Considerations — Elevated Administrator surface, C/C++ FFI & supply-chain analysis, RDP/VM graphics compatibility, stack sizing, and destructive guards.

Switches, Diagnostics, Reporting & Automation

  • Robocopy Switches & Presets — Complete Windows 10/11 switch map and detailed specification of all 8 built-in job presets.
  • Validation Rules & Exit Codes — All 16 validation codes (Error/Warning/Info) and complete 0..=16 bitmask exit decoding reference.
  • Reports, .rcj & Script Exports — Offline HTML/JSON/Markdown reports, legacy log importer, .rcj UTF-8/UTF-16 codec, .bat, .ps1, and schtasks.
  • CLI Reference — Global flags, two-stage Ctrl+C handler, and all 11 subcommands.
  • MCP Server Guide — JSON-RPC 2.0 stdio setup (mcp.json, Smithery), safe agent workflow, and all 9 MCP tools.

Clone this wiki locally