Repository navigation
Architecture
robocopy2rust is structured as a modular 7-crate Cargo workspace (edition = "2024", resolver 2). UI layers are strictly decoupled from core domain logic, process execution, reporting, CLI, and MCP automation.
flowchart LR
CORE["robocopy2rust-core<br/>Model, Quoting, Parsers, Validator,<br/>Exit Codes, Presets, Profiles"]
RUNNER["robocopy2rust-runner<br/>Host Env, CREATE_NO_WINDOW Runner,<br/>Output Parser, CancelToken, SHA-256"]
REPORT["robocopy2rust-report<br/>Air-gapped HTML / JSON / MD,<br/>Legacy Log Importer"]
MCP["robocopy2rust-mcp<br/>JSON-RPC 2.0 stdio Server<br/>9 Tools + Safety Guard"]
CLI["robocopy2rust-cli<br/>11 Subcommands + Dual GUI Launcher"]
WIN32["robocopy2rust-win32<br/>Native WinSafe 0.0.29 GUI<br/>Windows Default"]
ICED["robocopy2rust-iced<br/>Iced 0.14 Cross-Platform GUI<br/>Linux, macOS, Windows"]
RUNNER --> CORE
REPORT --> CORE
REPORT --> RUNNER
MCP --> CORE
MCP --> RUNNER
MCP --> REPORT
CLI --> CORE
CLI --> RUNNER
CLI --> REPORT
CLI --> MCP
WIN32 --> CORE
WIN32 --> RUNNER
WIN32 --> REPORT
ICED --> CORE
ICED --> RUNNER
ICED --> REPORT
Both GUIs (
robocopy2rust-win32androbocopy2rust-iced) share the exact same underlying engine (core+runner+report) and launch independently as lightweight OS-native processes viarobocopy2rust-cli.
Foundational library crate (crates/robocopy2rust-core/src/) containing all zero-UI business logic:
The canonical job model is RobocopyJob, organized into typed option groups:
-
CopyOptions(/S,/E,/LEV:n,/Z,/B,/ZB,/J,/EFSRAW,CopyFlags/COPY://SEC//COPYALL//NOCOPY,/SECFIX,/TIMFIX,/PURGE,/MIR,/MOV,/MOVE,FileAttrFlags/A+://A-:,/CREATE,/FAT,/256,/MON:n,/MOT:m,/RH:hhmm-hhmm,/PF,/IPG:n,/SJ,/SL,/MT[:n],DirCopyFlags/DCOPY://NODCOPY,/NOOFFLOAD,/COMPRESS,SparseMode/SPARSE[:Y|N],/NOCLONE). -
ThrottleOptions(/IoMaxSize:n[KMG],/IoRate:n[KMG],/Threshold:n[KMG]). -
FileSelectionOptions(/A,/M,/IA:,/XA:,/XF,/XD,/XC,/XN,/XO,/XX,/XL,/IS,/IT,/IM,/MAX:n,/MIN:n,/MAXAGE:,/MINAGE:,/MAXLAD:,/MINLAD:,/FFT,/DST,/XJ,/XJD,/XJF). -
RetryOptions(/R:n,/W:n,/REG,/TBD,/LFSM[:n[KMG]]). -
LoggingOptions(/L,/X,/V,/TS,/FP,/BYTES,/NS,/NC,/NFL,/NDL,/NP,/ETA,LogFileMode(/LOG:,/LOG+:,/UNILOG:,/UNILOG+:),/TEE,/NJH,/NJS,/UNICODE). -
JobFileOptions(/JOB:,/SAVE:,/QUIT,/NOSD,/NODD).
Important Default Constructors:
-
RobocopyJob::default()applies safe interactive defaults:/E(include empty subdirectories),/MT:8,/R:3,/W:5(preventing Robocopy's notorious 1,000,000-retry × 30-second stall), and/ETA. -
RobocopyJob::empty_cli_defaults()starts clean matching native Robocopy defaults so imported command lines and.rcjfiles only emit switches explicitly present in the input. - Helper methods
has_destructive_flags()(returnsfalsewhen/Lis active),destructive_switch_names(), andwith_list_only()(enables/L /FP /BYTESwhile clearing/NFL//NS//NCfor clear dry-run diffs).
Microsoft robocopy.exe uses C runtime CommandLineToArgvW rules where a trailing \ immediately before a closing double quote escapes the quote ("C:\Data\" corrupts argv).
-
normalize_robocopy_path(path): Trims whitespace/quotes and strips trailing/or\from non-root directories (C:\Users\Alice\→C:\Users\Alice,\\server\share\→\\server\share) while preserving drive roots (C:\, normalized fromC:/) and\. -
quote_windows_arg(arg): Wraps tokens containing spaces, tabs, quotes, or shell metacharacters (& | < > ^ ( ) ; , % !)—or ending with\—in double quotes and doubles trailing backslashes before quotes (C:\→"C:\\",C:\My Docs\→"C:\My Docs\\"). -
Ordered Argument Assembly (
build_args): Emitssource,destination,file_specs, copy flags, throttle flags, scalar selection flags, retry flags, logging flags, job-file flags, then multi-value/XFand/XDlists (placed after scalar switches so positional exclusions cannot capture switches), followed byextra_args.
-
tokenize_windows_cmdline&parse_command_line: Parses arbitraryrobocopy ...strings (stripping leadingrobocopy/robocopy.exe) according toCommandLineToArgvWescaping rules. Handles/SD:,/DD:, legacy or Windows 10/11 switches, and preserves unrecognized tokens insideextra_argswith parse warnings instead of dropping them. -
parse_rcj&serialize_rcj: Supports UTF-8, UTF-8 with BOM, UTF-16LE with BOM (Windows/SAVE:native encoding), and UTF-16BE with BOM; parses/SD:,/DD:,/IF,/XF,/XDsections and strips inline:: commentmarkers without truncating quoted paths.
Validation, Exit Decoding, Presets & Persistence (validation.rs, exit_code.rs, presets.rs, profiles.rs, logging.rs)
-
Validation Engine: Evaluates 16 rules across
Error,Warning, andInfoseverities (details in Validation Rules & Exit Codes). -
Exit Code Decoder: Decodes bitmask codes (
0..=7success,>= 8failure,< 0cancelled/terminated). -
Persistent Store (
ProfileStore): Storesprofiles.jsonandhistory.jsonunderdirs::config_dir()/robocopy2rust(%APPDATA%\robocopy2ruston Windows) using atomic temporary-file writes (.json.tmp→ rename) and capping run history at the 200 most recent runs. -
Logging (
init_logging): Usestracing_subscriberwriting strictly tostderr(or an explicit log file) so CLI JSON stdout and MCPstdioJSON-RPC channels are never corrupted.
Process execution and real-time output parsing crate (crates/robocopy2rust-runner/src/):
-
Environment Probe (
env.rs):find_robocopy_executable()checksC:\Windows\System32\robocopy.exefirst on Windows (preventingPATHshadowing), then scansPATH;detect_environment()reports OS, availability, resolved path, and config directory. -
Live Streaming Executor (
runner.rs):-
spawn_job_runnerspawns a background OS worker thread streamingRunnerEventvariants (Started,LogLine,FileAction,Progress,Error,Summary,Finished) overstd::sync::mpsc. - Sets
CREATE_NO_WINDOW(0x0800_0000) on Windows so GUI/headless runs never flash transient console windows. -
stream_linesreads raw bytes in 4 KB chunks and splits on both\rand\n(collapsing\r\n), delivering Robocopy's in-placexx.x%progress carriage returns immediately without waiting for file completion. - Computes a continuous SHA-256 digest (
log_sha256) across all stdout/stderr log lines. -
CancelTokenstores anAtomicBool, child PID, and cross-platform killer closure (taskkill /PID <pid> /T /FwithCREATE_NO_WINDOWon Windows;kill -TERM <pid>on Unix) to terminate child trees cleanly. Cancelled runs report exit code-1andcancelled: true.
-
-
Stateful Output Parser (
output_parser.rs): Classifies 15FileActionKindvariants (NewFile,Newer,Older,Changed,Same,ExtraFile,ExtraDir,NewDir,Tweaked,Modified,Lonely,Mismatch,Failed,DirEntry,Other), regex-matchesERROR <n> (...)andWaiting <n> seconds... Retryinglines, disambiguates headerFiles : *.*from summaryFiles : total copied ..., and parses[KMGTP]size suffixes plusBytes/sec./MegaBytes/min.throughput.
-
robocopy2rust-report: Emits self-contained offline HTML (inline CSS + JS filter + dark/light toggle), schema-versioned JSON (robocopy2rust.audit.v1), and Markdown reports, plus imports legacy UTF-8/UTF-16 Robocopy logs. See Reports, .rcj & Script Exports. -
robocopy2rust-mcp: Exposes 9 JSON-RPC 2.0 tools overstdio(2024-11-05) with strict destructive safety checks. See MCP Server Guide. -
robocopy2rust-cli: Exposes 11 subcommands plus argumentless GUI launching (robocopy2rust-win32default on Windows;robocopy2rust-icedon Linux/macOS or via--iced). See CLI Reference. -
robocopy2rust-win32&robocopy2rust-iced: Twin pure-Rust desktop consoles covered in Dual-GUI Guide.
robocopy2rust (v0.1.0) • GUAP Ecosystem (guap.ca) • Rust 2024 Edition • Apache-2.0 License • Repository • Security Policy