spoof-d 0.1.0 → 0.2.0

package/.spoofyrc.example

@@ -0,0 +1,10 @@
+{
+  "randomize": {
+    "local": false
+  },
+  "defaults": {
+    "verbose": false,
+    "json": false
+  }
+}
+

package/README.md

@@ -50,6 +50,12 @@ This repository ([TT5H/spoof-d](https://github.com/TT5H/spoof-d)) is a fork of [
 - **Linux**: Modern ip link commands with ifconfig fallback
 - **Unified API** across all platforms
 
+### User Experience Features
+- **Progress indicators** for long-running operations
+- **Verbose mode** (`--verbose`) for detailed debugging output
+- **JSON output** (`--json`) for scripting and automation
+- **Configuration file** support (`.spoofyrc` in home directory)
+
 ## Installation
 
 ### From npm (recommended)
@@ -159,6 +165,62 @@ sudo spoofy reset wi-fi
 
 **Note**: On macOS, restarting your computer will also reset your MAC address to the original hardware address.
 
+## Advanced Usage
+
+### Verbose Mode
+
+Get detailed debugging information:
+
+```bash
+spoofy list --verbose
+spoofy randomize en0 --verbose
+```
+
+### JSON Output
+
+Output results in JSON format for scripting:
+
+```bash
+spoofy list --json
+spoofy randomize en0 --json
+```
+
+Example JSON output:
+```json
+{
+  "success": true,
+  "device": "en0",
+  "mac": "00:11:22:33:44:55",
+  "message": "MAC address changed successfully"
+}
+```
+
+### Configuration File
+
+Create a configuration file at `~/.spoofyrc` (or `%USERPROFILE%\.spoofyrc` on Windows):
+
+```json
+{
+  "randomize": {
+    "local": true
+  },
+  "defaults": {
+    "verbose": false,
+    "json": false
+  }
+}
+```
+
+The configuration file allows you to set default options that will be used automatically.
+
+### Progress Indicators
+
+Long-running operations show progress indicators:
+
+```bash
+⏳ Changing MAC address... ✓ Successfully set MAC address
+```
+
 ## Platform Support
 
 ### macOS ✅

package/bin/cmd.js

@@ -5,15 +5,73 @@ const minimist = require("minimist");
 const spoof = require("../");
 const { stripIndent } = require("common-tags");
 const cp = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
 
 const argv = minimist(process.argv.slice(2), {
   alias: {
     v: "version",
+    V: "verbose",
+    j: "json",
   },
-  boolean: ["version"],
+  boolean: ["version", "verbose", "json"],
 });
 const cmd = argv._[0];
 
+// Global flags
+const VERBOSE = argv.verbose || false;
+const JSON_OUTPUT = argv.json || false;
+
+// Configuration file support
+let config = null;
+const configPath = path.join(os.homedir(), ".spoofyrc");
+if (fs.existsSync(configPath)) {
+  try {
+    const configContent = fs.readFileSync(configPath, "utf8");
+    config = JSON.parse(configContent);
+    if (VERBOSE) {
+      logVerbose(`Loaded configuration from ${configPath}`);
+    }
+  } catch (err) {
+    if (VERBOSE) {
+      logVerbose(`Failed to load config: ${err.message}`);
+    }
+  }
+}
+
+// Helper functions
+function logVerbose(message) {
+  if (VERBOSE && !JSON_OUTPUT) {
+    console.error(chalk.gray(`[VERBOSE] ${message}`));
+  }
+}
+
+function outputJSON(data) {
+  if (JSON_OUTPUT) {
+    console.log(JSON.stringify(data, null, 2));
+  }
+}
+
+function showProgress(message) {
+  if (JSON_OUTPUT) return;
+  process.stdout.write(chalk.blue("⏳ ") + message + "... ");
+}
+
+function hideProgress() {
+  if (JSON_OUTPUT) return;
+  process.stdout.write("\r" + " ".repeat(80) + "\r");
+}
+
+function progressStep(step, total, message) {
+  if (JSON_OUTPUT) return;
+  const percentage = Math.round((step / total) * 100);
+  process.stdout.write(`\r${chalk.blue("⏳")} [${step}/${total}] ${percentage}% - ${message}...`);
+  if (step === total) {
+    process.stdout.write("\r" + " ".repeat(80) + "\r");
+  }
+}
+
 try {
   init();
 } catch (err) {
@@ -117,6 +175,8 @@ ${example}${note}
     Options:
       --wifi          Try to only show wireless interfaces.
       --local         Set the locally administered flag on randomized MACs.
+      --verbose, -V   Show verbose output for debugging.
+      --json, -j     Output results in JSON format.
 
     Platform Support:
       ✅ macOS (Sequoia 15.4+, Tahoe 26+)
@@ -127,7 +187,16 @@ ${example}${note}
 }
 
 function version() {
-  console.log(require("../package.json").version);
+  const pkg = require("../package.json");
+  if (JSON_OUTPUT) {
+    outputJSON({
+      version: pkg.version,
+      name: pkg.name,
+      description: pkg.description,
+    });
+  } else {
+    console.log(pkg.version);
+  }
 }
 
 function set(mac, devices) {
@@ -139,8 +208,14 @@ function set(mac, devices) {
     throw new Error("Device name is required. Usage: spoofy set <mac> <device>");
   }
   
-  devices.forEach((device) => {
+  logVerbose(`Setting MAC address ${mac} on ${devices.length} device(s)`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -149,6 +224,7 @@ function set(mac, devices) {
       );
     }
 
+    logVerbose(`Found interface: ${it.device} (port: ${it.port})`);
     setMACAddress(it.device, mac, it.port);
   });
 }
@@ -158,13 +234,34 @@ function normalize(mac) {
     throw new Error("MAC address is required. Usage: spoofy normalize <mac>");
   }
   
+  logVerbose(`Normalizing MAC address: ${mac}`);
+  
   try {
     const normalized = spoof.normalize(mac);
     if (!normalized) {
       throw new Error(`"${mac}" is not a valid MAC address`);
     }
-    console.log(normalized);
+    
+    if (JSON_OUTPUT) {
+      outputJSON({
+        original: mac,
+        normalized: normalized,
+        valid: true,
+      });
+    } else {
+      console.log(normalized);
+    }
+    
+    logVerbose(`Normalized: ${mac} -> ${normalized}`);
   } catch (err) {
+    if (JSON_OUTPUT) {
+      outputJSON({
+        original: mac,
+        normalized: null,
+        valid: false,
+        error: err.message,
+      });
+    }
     throw new Error(
       `Could not normalize MAC address "${mac}": ${err.message}`
     );
@@ -176,8 +273,15 @@ function randomize(devices) {
     throw new Error("Device name is required. Usage: spoofy randomize <device>");
   }
   
-  devices.forEach((device) => {
+  const useLocal = argv.local || (config && config.randomize && config.randomize.local);
+  logVerbose(`Randomizing MAC address (local: ${useLocal})`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -186,8 +290,15 @@ function randomize(devices) {
       );
     }
 
-    const mac = spoof.randomize(argv.local);
-    console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
+    logVerbose(`Found interface: ${it.device} (port: ${it.port})`);
+    const mac = spoof.randomize(useLocal);
+    
+    if (JSON_OUTPUT) {
+      // Will be output in setMACAddress
+    } else {
+      console.log(chalk.blue("ℹ"), `Generated random MAC address: ${chalk.bold.cyan(mac)}`);
+    }
+    
     setMACAddress(it.device, mac, it.port);
   });
 }
@@ -197,8 +308,14 @@ function reset(devices) {
     throw new Error("Device name is required. Usage: spoofy reset <device>");
   }
   
-  devices.forEach((device) => {
+  logVerbose(`Resetting MAC address on ${devices.length} device(s)`);
+  
+  devices.forEach((device, index) => {
+    logVerbose(`Processing device ${index + 1}/${devices.length}: ${device}`);
+    showProgress(`Finding interface ${device}`);
+    
     const it = spoof.findInterface(device);
+    hideProgress();
 
     if (!it) {
       throw new Error(
@@ -214,12 +331,22 @@ function reset(devices) {
       );
     }
 
-    console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
+    logVerbose(`Hardware MAC address: ${it.address}`);
+    
+    if (JSON_OUTPUT) {
+      // Will be output in setMACAddress
+    } else {
+      console.log(chalk.blue("ℹ"), `Resetting to hardware MAC address: ${chalk.bold.cyan(it.address)}`);
+    }
+    
     setMACAddress(it.device, it.address, it.port);
   });
 }
 
 function list() {
+  logVerbose("Starting interface discovery...");
+  showProgress("Discovering network interfaces");
+  
   const targets = [];
   if (argv.wifi) {
     if (process.platform === "win32") {
@@ -230,6 +357,23 @@ function list() {
   }
 
   const interfaces = spoof.findInterfaces(targets);
+  hideProgress();
+  logVerbose(`Found ${interfaces.length} interface(s)`);
+
+  if (JSON_OUTPUT) {
+    outputJSON({
+      interfaces: interfaces.map((it) => ({
+        port: it.port || it.device,
+        device: it.device,
+        address: it.address,
+        currentAddress: it.currentAddress,
+        status: it.status,
+        description: it.description,
+      })),
+      count: interfaces.length,
+    });
+    return;
+  }
 
   if (interfaces.length === 0) {
     console.log(chalk.yellow("No network interfaces found."));
@@ -260,8 +404,11 @@ function list() {
 }
 
 function setMACAddress(device, mac, port) {
+  logVerbose(`Setting MAC address ${mac} on device ${device}`);
+  
   // Check for admin/root privileges
   if (process.platform === "win32") {
+    logVerbose("Checking for Administrator privileges...");
     // On Windows, check if running as administrator
     try {
       const output = cp
@@ -279,34 +426,66 @@ function setMACAddress(device, mac, port) {
           "Right-click Command Prompt or PowerShell and select 'Run as Administrator'"
         );
       }
+      logVerbose("Administrator privileges confirmed");
     } catch (err) {
       if (err.message.includes("Must run as Administrator")) {
         throw err;
       }
       // If check fails, warn but continue (might work anyway)
-      console.warn(chalk.yellow("Warning: Could not verify administrator privileges. Operation may fail."));
+      if (!JSON_OUTPUT) {
+        console.warn(chalk.yellow("Warning: Could not verify administrator privileges. Operation may fail."));
+      }
+      logVerbose("Could not verify privileges, continuing anyway");
     }
   } else if (process.platform !== "win32") {
+    logVerbose("Checking for root privileges...");
     // Unix-like systems (macOS, Linux)
     if (process.getuid && process.getuid() !== 0) {
       throw new Error(
         "Must run as root (or using sudo) to change network settings"
       );
     }
+    logVerbose("Root privileges confirmed");
   }
 
   try {
+    showProgress("Changing MAC address");
+    logVerbose(`Calling setInterfaceMAC(${device}, ${mac}, ${port})`);
+    
     spoof.setInterfaceMAC(device, mac, port);
-    console.log(
-      chalk.green("✓") +
-      " Successfully set MAC address to " +
-      chalk.bold.cyan(mac) +
-      " on " +
-      chalk.bold.green(device)
-    );
     
+    hideProgress();
+    
+    if (JSON_OUTPUT) {
+      outputJSON({
+        success: true,
+        device: device,
+        mac: mac,
+        message: "MAC address changed successfully",
+      });
+    } else {
+      console.log(
+        chalk.green("✓") +
+        " Successfully set MAC address to " +
+        chalk.bold.cyan(mac) +
+        " on " +
+        chalk.bold.green(device)
+      );
+    }
+    
+    logVerbose("MAC address change completed successfully");
     // Note: Verification is already done in setInterfaceMAC, so we don't need to do it again here
   } catch (err) {
+    hideProgress();
+    if (JSON_OUTPUT) {
+      outputJSON({
+        success: false,
+        device: device,
+        mac: mac,
+        error: err.message,
+        code: err.code,
+      });
+    }
     // Error is already formatted by handleError in the catch block above
     throw err;
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "spoof-d",
   "description": "Cross-platform MAC address spoofing utility for macOS, Windows, and Linux",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "bin": {
     "spoofy": "./bin/cmd.js"
   },
@@ -9,7 +9,8 @@
     "index.js",
     "bin/",
     "LICENSE",
-    "README.md"
+    "README.md",
+    ".spoofyrc.example"
   ],
   "bugs": {
     "url": "https://github.com/TT5H/spoof-d/issues"