fix(cli): validate artifact arguments and implement object debug output (#292)

Signed-off-by: LunaStev <luna@lunastev.org>

Author: LunaStev

README.md

@@ -108,6 +108,30 @@ cargo run --release --locked -- asm --amd64 example.asm -o example.o
 This produces a relocatable ELF64 object. Assembly is implemented within Whale;
 no external assembler is needed.
 
+The `asm` and `object` commands reject unknown options, extra input paths,
+duplicate `-o` options, and missing output paths before reading input or writing
+output. Specify the assembly architecture once. For a path beginning with `-`,
+use a relative `./` prefix or an absolute path.
+
+### Wrap raw bytes in an object
+
+```sh
+cargo run --locked -- object raw.bin -o raw.o
+cargo run --locked -- object --help
+```
+
+This places the input bytes in an AMD64 ELF64 `.text` section with a global
+`start` symbol. The input must already contain the intended machine code.
+
+Both `asm` and `object` support `--debug-whale` with `--bytes`, `--dump-hex`,
+`--dump-bin`, or `--dump-json` to inspect the first 256 bytes of the emitted
+object. JSON includes the full object length and a bounded byte array.
+For example:
+
+```sh
+cargo run --locked -- object raw.bin -o raw.o --debug-whale --dump-hex
+```
+
 ### Execute scalar integer IR
 
 Save this format 4 module as `answer.wir`:

src/cli.rs

@@ -11,6 +11,7 @@ pub fn run() {
     };
 
     match cmd.as_str() {
+        "--help" | "-h" => print_help(),
         "asm" => commands::asm::run(args.collect()),
         "object" => commands::object::run(args.collect()),
         "link" => commands::linker::run(args.collect()),
@@ -25,14 +26,14 @@ pub fn run() {
 
 fn print_help() {
     println!("Usage:");
-    println!("  whale asm [--amd64 | --aarch64] <input> -o <output>");
+    println!("  whale asm --amd64 <input> -o <output.o>");
     println!("  whale object <input> -o <output>");
     println!("  whale link <...>");
     println!("  whale ir <subcommand> [options]");
     println!();
     println!("Commands:");
-    println!("  asm     Assemble source file");
-    println!("  object  Generate object file from binary or IR");
-    println!("  link    Link object files into an executable");
-    println!("  ir      IR tools (verify/print; socket-cli enables AST lower)");
+    println!("  asm     Assemble AMD64 source into an ELF64 object");
+    println!("  object  Wrap raw bytes in an AMD64 ELF64 object");
+    println!("  link    Executable linking (not implemented)");
+    println!("  ir      IR tools (verify/print/run; socket-cli enables AST lower)");
 }

src/commands/asm.rs

@@ -2,6 +2,8 @@ use std::fs;
 use std::process;
 use std::time::Instant;
 
+use super::debug::dump_bytes;
+
 use assembler::isa::amd64::parser::parse;
 use assembler::tokens::tokenize;
 use assembler::{assemble, isa::AMD64, AssemblerOutput};
@@ -41,14 +43,32 @@ pub fn run(args: Vec<String>) {
                 return;
             }
 
-            "--amd64" => arch = Some("amd64"),
-            "--aarch64" => arch = Some("aarch64"),
+            flag @ ("--amd64" | "--aarch64") => {
+                if arch.is_some() {
+                    eprintln!("Error: architecture must be specified only once");
+                    process::exit(1);
+                }
+                arch = Some(if flag == "--amd64" {
+                    "amd64"
+                } else {
+                    "aarch64"
+                });
+            }
 
             "-o" => {
-                if i + 1 < args.len() {
-                    output = Some(args[i + 1].clone());
-                    i += 1;
+                if output.is_some() {
+                    eprintln!("Error: duplicate -o option");
+                    process::exit(1);
                 }
+                let path = args
+                    .get(i + 1)
+                    .filter(|s| !s.starts_with('-'))
+                    .unwrap_or_else(|| {
+                        eprintln!("Error: -o requires a path (use ./ for paths starting with '-')");
+                        process::exit(1);
+                    });
+                output = Some(path.clone());
+                i += 1;
             }
 
             "--debug-whale" => debug_mode = true,
@@ -64,7 +84,15 @@ pub fn run(args: Vec<String>) {
             "--trace" => trace_enable = true,
 
             s if input.is_none() && !s.starts_with('-') => input = Some(s.to_string()),
-            _ => {}
+            s => {
+                let kind = if s.starts_with('-') {
+                    "unknown option"
+                } else {
+                    "unexpected argument"
+                };
+                eprintln!("Error: {kind}: {s}");
+                process::exit(1);
+            }
         }
         i += 1;
     }
@@ -273,64 +301,6 @@ fn build_elf_from_asm_output(out: &AssemblerOutput) -> Result<Vec<u8>, String> {
     obj.write()
 }
 
-fn dump_bytes(
-    label: &str,
-    bytes: &[u8],
-    show_bytes: bool,
-    dump_hex: bool,
-    dump_bin: bool,
-    dump_json: bool,
-) {
-    const LIMIT: usize = 256;
-    let n = bytes.len().min(LIMIT);
-    let head = &bytes[..n];
-
-    if show_bytes {
-        println!(
-            "== BYTES ({}, {} bytes, head {} bytes) ==",
-            label,
-            bytes.len(),
-            n
-        );
-        for (i, b) in head.iter().enumerate() {
-            println!("{:04X}: {}", i, b);
-        }
-    }
-
-    if dump_hex {
-        println!("== HEX ({}, head {} bytes) ==", label, n);
-        for (i, chunk) in head.chunks(16).enumerate() {
-            print!("{:04X}: ", i * 16);
-            for b in chunk {
-                print!("{:02X} ", b);
-            }
-            println!();
-        }
-    }
-
-    if dump_bin {
-        println!("== BIN ({}, head {} bytes) ==", label, n);
-        for (i, b) in head.iter().enumerate() {
-            println!("{:04X}: {:08b}", i, b);
-        }
-    }
-
-    if dump_json {
-        println!("== JSON ({}) ==", label);
-        println!("{{");
-        println!("  \"len\": {},", bytes.len());
-        print!("  \"head\": [");
-        for (i, b) in head.iter().enumerate() {
-            if i != 0 {
-                print!(", ");
-            }
-            print!("{}", b);
-        }
-        println!("]");
-        println!("}}");
-    }
-}
-
 fn print_help() {
     println!("Usage:");
     println!("  whale asm --amd64 <input> -o <output.o>");

src/commands/debug.rs

@@ -0,0 +1,57 @@
+pub(super) fn dump_bytes(
+    label: &str,
+    bytes: &[u8],
+    show_bytes: bool,
+    dump_hex: bool,
+    dump_bin: bool,
+    dump_json: bool,
+) {
+    const LIMIT: usize = 256;
+    let n = bytes.len().min(LIMIT);
+    let head = &bytes[..n];
+
+    if show_bytes {
+        println!(
+            "== BYTES ({}, {} bytes, head {} bytes) ==",
+            label,
+            bytes.len(),
+            n
+        );
+        for (i, b) in head.iter().enumerate() {
+            println!("{:04X}: {}", i, b);
+        }
+    }
+
+    if dump_hex {
+        println!("== HEX ({}, head {} bytes) ==", label, n);
+        for (i, chunk) in head.chunks(16).enumerate() {
+            print!("{:04X}: ", i * 16);
+            for b in chunk {
+                print!("{:02X} ", b);
+            }
+            println!();
+        }
+    }
+
+    if dump_bin {
+        println!("== BIN ({}, head {} bytes) ==", label, n);
+        for (i, b) in head.iter().enumerate() {
+            println!("{:04X}: {:08b}", i, b);
+        }
+    }
+
+    if dump_json {
+        println!("== JSON ({}) ==", label);
+        println!("{{");
+        println!("  \"len\": {},", bytes.len());
+        print!("  \"head\": [");
+        for (i, b) in head.iter().enumerate() {
+            if i != 0 {
+                print!(", ");
+            }
+            print!("{}", b);
+        }
+        println!("]");
+        println!("}}");
+    }
+}

src/commands/mod.rs

@@ -1,4 +1,5 @@
 pub mod asm;
+mod debug;
 pub mod linker;
 pub mod object;
 mod output;

src/commands/object.rs

@@ -3,6 +3,8 @@ use std::fs;
 use std::process;
 use std::time::Instant;
 
+use super::debug::dump_bytes;
+
 pub fn run(args: Vec<String>) {
     if args.is_empty() {
         print_help();
@@ -13,14 +15,10 @@ pub fn run(args: Vec<String>) {
     let mut output = None;
 
     let mut debug_mode = false;
-    let mut _show_ast = false;
-    let mut _show_token = false;
     let mut show_bytes = false;
     let mut dump_hex = false;
     let mut dump_bin = false;
-    let mut _dump_json = false;
-    let mut _no_color = false;
-    let mut _no_warn_ext = false;
+    let mut dump_json = false;
     let mut show_stats = false;
     let mut trace_enable = false;
 
@@ -32,20 +30,37 @@ pub fn run(args: Vec<String>) {
                 return;
             }
             "-o" => {
-                if i + 1 < args.len() {
-                    output = Some(args[i + 1].clone());
-                    i += 1;
+                if output.is_some() {
+                    eprintln!("Error: duplicate -o option");
+                    process::exit(1);
                 }
+                let path = args
+                    .get(i + 1)
+                    .filter(|s| !s.starts_with('-'))
+                    .unwrap_or_else(|| {
+                        eprintln!("Error: -o requires a path (use ./ for paths starting with '-')");
+                        process::exit(1);
+                    });
+                output = Some(path.clone());
+                i += 1;
             }
             "--debug-whale" => debug_mode = true,
             "--bytes" => show_bytes = true,
             "--dump-hex" => dump_hex = true,
             "--dump-bin" => dump_bin = true,
-            "--dump-json" => _dump_json = true,
+            "--dump-json" => dump_json = true,
             "--stats" => show_stats = true,
             "--trace" => trace_enable = true,
             s if input.is_none() && !s.starts_with('-') => input = Some(s.to_string()),
-            _ => {}
+            s => {
+                let kind = if s.starts_with('-') {
+                    "unknown option"
+                } else {
+                    "unexpected argument"
+                };
+                eprintln!("Error: {kind}: {s}");
+                process::exit(1);
+            }
         }
         i += 1;
     }
@@ -88,13 +103,17 @@ pub fn run(args: Vec<String>) {
     });
     let elapsed = start_time.elapsed();
 
-    if debug_mode && (show_bytes || dump_hex || dump_bin) { /* ... same as before ... */ }
-
     super::output::publish(input.as_ref(), output.as_ref(), &out_bytes).unwrap_or_else(|e| {
         eprintln!("Failed to write {output}: {e}");
         process::exit(1);
     });
 
+    if debug_mode && (show_bytes || dump_hex || dump_bin || dump_json) {
+        dump_bytes(
+            "object", &out_bytes, show_bytes, dump_hex, dump_bin, dump_json,
+        );
+    }
+
     if debug_mode && show_stats {
         println!(
             "== STATS ==\nInput bytes: {}\nOutput bytes: {}\nTime: {} ms",
@@ -106,5 +125,19 @@ pub fn run(args: Vec<String>) {
     println!("Created object file {} ({} bytes)", output, out_bytes.len());
 }
 
-pub fn print_help() { /* ... same as before ... */
+pub fn print_help() {
+    println!("Usage:");
+    println!("  whale object <input> -o <output>");
+    println!();
+    println!("Wrap raw bytes in an AMD64 ELF64 object with a .text section.");
+    println!();
+    println!("Options:");
+    println!("  --help          show this help");
+    println!("  --debug-whale   enable debug features");
+    println!("  --bytes         print object bytes (debug, first 256 bytes)");
+    println!("  --dump-hex      print object bytes as hex (debug, first 256 bytes)");
+    println!("  --dump-bin      print object bytes as binary (debug, first 256 bytes)");
+    println!("  --dump-json     print object size and byte head as JSON (debug)");
+    println!("  --stats         show stats (debug)");
+    println!("  --trace         trace logs");
 }