@fredlackey/devutils 0.0.1 → 0.0.3

package/src/scripts/map.js

@@ -1,24 +1,309 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Execute a command for each line of input.
+ * map - Execute a command for each line of input
+ *
+ * Migrated from legacy dotfiles alias.
+ * Original: alias map="xargs -n1"
+ *
+ * This script reads lines from stdin and executes the specified command
+ * for each line, similar to `xargs -n1`. It allows you to "map" a command
+ * over a list of inputs.
+ *
+ * Usage examples:
+ *   echo -e "file1.txt\nfile2.txt" | map cat
+ *   ls *.js | map wc -l
+ *   git branch | map git log -1 --oneline
+ *
+ * The input line is passed as the last argument to the command. For example:
+ *   echo "hello" | map echo "Processing:"
+ *   # Executes: echo "Processing:" "hello"
+ *
  * @module scripts/map
  */
 
+const os = require('../utils/common/os');
+const { spawn } = require('child_process');
+const readline = require('readline');
+
+/**
+ * Pure Node.js implementation that works on any platform.
+ *
+ * This function reads lines from stdin and executes the specified command
+ * for each line. The input line is appended as the last argument to the command.
+ *
+ * Why this works cross-platform:
+ * - readline module handles stdin consistently across all platforms
+ * - spawn works identically on macOS, Linux, and Windows
+ * - No platform-specific shell features are used
+ *
+ * @param {string[]} args - Command and its arguments. The first element is the
+ *                          command to run, remaining elements are arguments.
+ *                          The input line is appended as the final argument.
+ * @returns {Promise<void>}
+ */
+async function do_map_nodejs(args) {
+  // If no command provided, show usage information
+  if (args.length === 0) {
+    console.log('Usage: map <command> [arguments...]');
+    console.log('');
+    console.log('Reads lines from stdin and executes the command for each line.');
+    console.log('The input line is passed as the last argument to the command.');
+    console.log('');
+    console.log('Examples:');
+    console.log('  echo -e "file1.txt\\nfile2.txt" | map cat');
+    console.log('  ls *.js | map wc -l');
+    console.log('  find . -name "*.txt" | map head -1');
+    console.log('');
+    console.log('Similar to: xargs -n1');
+    return;
+  }
+
+  // Extract the command (first argument) and its base arguments (remaining arguments)
+  const command = args[0];
+  const baseArgs = args.slice(1);
+
+  // Create readline interface to read lines from stdin
+  const rl = readline.createInterface({
+    input: process.stdin,
+    // Don't output to terminal - we're reading piped data
+    terminal: false
+  });
+
+  // Collect all lines first, then process them sequentially
+  // This ensures commands complete in order and errors are handled properly
+  const lines = [];
+
+  for await (const line of rl) {
+    // Skip empty lines to avoid passing empty arguments
+    const trimmedLine = line.trim();
+    if (trimmedLine !== '') {
+      lines.push(trimmedLine);
+    }
+  }
+
+  // If no input was provided (empty stdin), inform the user
+  if (lines.length === 0) {
+    console.error('No input received. Pipe data to this command:');
+    console.error('  echo "item1\\nitem2" | map <command>');
+    return;
+  }
+
+  // Process each line sequentially
+  // Sequential processing ensures output is predictable and ordered
+  for (const inputLine of lines) {
+    // Build the full argument list: base args + the input line
+    const fullArgs = [...baseArgs, inputLine];
+
+    try {
+      // Execute the command and wait for it to complete
+      await executeCommand(command, fullArgs);
+    } catch (error) {
+      // Continue processing remaining lines even if one fails
+      // This matches xargs behavior by default
+      console.error(`Error processing "${inputLine}": ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Execute a command with given arguments and return a promise.
+ *
+ * Uses spawn instead of exec to:
+ * - Handle large output without buffer limits
+ * - Stream output in real-time
+ * - Better handle signals and process lifecycle
+ *
+ * @param {string} command - The command to execute
+ * @param {string[]} args - Arguments to pass to the command
+ * @returns {Promise<void>} Resolves when command completes, rejects on error
+ */
+function executeCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    // Determine if we're on Windows to set appropriate shell option
+    const isWindows = process.platform === 'win32';
+
+    // Spawn the child process
+    // - shell: true allows running shell built-ins and handles PATH lookup
+    // - stdio: 'inherit' connects child's stdin/stdout/stderr to parent
+    const child = spawn(command, args, {
+      shell: true,
+      stdio: 'inherit',
+      // On Windows, use cmd.exe; on Unix, use default shell
+      ...(isWindows && { windowsHide: true })
+    });
+
+    // Handle process completion
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        // Non-zero exit code indicates command failed
+        reject(new Error(`Command exited with code ${code}`));
+      }
+    });
+
+    // Handle spawn errors (command not found, permission denied, etc.)
+    child.on('error', (error) => {
+      reject(error);
+    });
+  });
+}
+
+/**
+ * Execute a command for each line of input on macOS.
+ *
+ * macOS can use the pure Node.js implementation since no platform-specific
+ * features are required for this functionality.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_macos(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Execute a command for each line of input on Ubuntu.
+ *
+ * Ubuntu can use the pure Node.js implementation since no platform-specific
+ * features are required for this functionality.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_ubuntu(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Execute a command for each line of input on Raspberry Pi OS.
+ *
+ * Raspberry Pi OS can use the pure Node.js implementation since no
+ * platform-specific features are required for this functionality.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_raspbian(args) {
+  return do_map_nodejs(args);
+}
+
 /**
- * Reads lines from stdin and executes the specified command
- * for each line, similar to `xargs -n1`.
+ * Execute a command for each line of input on Amazon Linux.
+ *
+ * Amazon Linux can use the pure Node.js implementation since no
+ * platform-specific features are required for this functionality.
  *
  * @param {string[]} args - Command line arguments
- * @param {string} args.0 - Command to execute for each input line
  * @returns {Promise<void>}
  */
-async function main(args) {
-  // TODO: Implement xargs-like mapping
+async function do_map_amazon_linux(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Execute a command for each line of input in Windows Command Prompt.
+ *
+ * Windows CMD can use the pure Node.js implementation. The spawn command
+ * with shell: true automatically uses cmd.exe on Windows.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_cmd(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Execute a command for each line of input in Windows PowerShell.
+ *
+ * Windows PowerShell can use the pure Node.js implementation. The spawn
+ * command with shell: true works correctly from PowerShell.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_powershell(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Execute a command for each line of input in Git Bash.
+ *
+ * Git Bash can use the pure Node.js implementation since no platform-specific
+ * features are required for this functionality.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_map_gitbash(args) {
+  return do_map_nodejs(args);
+}
+
+/**
+ * Main entry point - detects environment and executes appropriate implementation.
+ *
+ * The "map" command reads lines from stdin and executes a command for each line,
+ * similar to `xargs -n1`. This is useful for applying a command to each item in
+ * a list, such as:
+ *
+ *   - Processing each file from a directory listing
+ *   - Applying a git command to multiple branches
+ *   - Running a script on each item from a search result
+ *
+ * @param {string[]} args - Command line arguments. First argument is the command
+ *                          to run, remaining arguments are passed to that command.
+ * @returns {Promise<void>}
+ */
+async function do_map(args) {
+  const platform = os.detect();
+
+  const handlers = {
+    'macos': do_map_macos,
+    'ubuntu': do_map_ubuntu,
+    'debian': do_map_ubuntu,
+    'raspbian': do_map_raspbian,
+    'amazon_linux': do_map_amazon_linux,
+    'rhel': do_map_amazon_linux,
+    'fedora': do_map_ubuntu,
+    'linux': do_map_ubuntu,
+    'wsl': do_map_ubuntu,
+    'cmd': do_map_cmd,
+    'windows': do_map_cmd,
+    'powershell': do_map_powershell,
+    'gitbash': do_map_gitbash
+  };
+
+  const handler = handlers[platform.type];
+  if (!handler) {
+    console.error(`Platform '${platform.type}' is not supported for this command.`);
+    console.error('');
+    console.error('Supported platforms:');
+    console.error('  - macOS');
+    console.error('  - Ubuntu, Debian, and other Linux distributions');
+    console.error('  - Raspberry Pi OS');
+    console.error('  - Amazon Linux, RHEL, Fedora');
+    console.error('  - Windows (CMD, PowerShell, Git Bash)');
+    process.exit(1);
+  }
+
+  await handler(args);
 }
 
-module.exports = { main };
+module.exports = {
+  main: do_map,
+  do_map,
+  do_map_nodejs,
+  do_map_macos,
+  do_map_ubuntu,
+  do_map_raspbian,
+  do_map_amazon_linux,
+  do_map_cmd,
+  do_map_powershell,
+  do_map_gitbash
+};
 
 if (require.main === module) {
-  main(process.argv.slice(2));
+  do_map(process.argv.slice(2));
 }

package/src/scripts/mkd.js

@@ -1,24 +1,304 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Create directory and navigate into it.
+ * mkd - Create a new directory and display navigation instructions
+ *
+ * Migrated from legacy dotfiles function.
+ * Original:
+ *   mkd() {
+ *       mkdir -p "$@" && cd "$@"
+ *   }
+ *
+ * This script creates a new directory (including all necessary parent directories)
+ * and outputs instructions for navigating into it. The original shell function could
+ * change the working directory directly, but since Node.js scripts run in a subprocess,
+ * they cannot modify the parent shell's working directory.
+ *
+ * Usage:
+ *   mkd my-project                    # Creates ./my-project
+ *   mkd path/to/nested/directory      # Creates all parent directories as needed
+ *   mkd ~/projects/new-app            # Works with home directory paths
+ *
  * @module scripts/mkd
  */
 
+const os = require('../utils/common/os');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Expands a path that starts with ~ to the user's home directory.
+ *
+ * Node.js doesn't automatically expand tilde in paths like shells do,
+ * so we need to handle this manually for user convenience.
+ *
+ * @param {string} inputPath - The path that may contain a leading ~
+ * @returns {string} The expanded path with ~ replaced by home directory
+ */
+function expandTilde(inputPath) {
+  // If the path starts with ~, replace it with the home directory
+  if (inputPath.startsWith('~')) {
+    const homeDir = os.getHomeDir();
+    // Handle both ~/path and ~ alone
+    return inputPath.replace(/^~/, homeDir);
+  }
+  return inputPath;
+}
+
+/**
+ * Pure Node.js implementation for creating directories.
+ *
+ * Uses the Node.js fs module to create directories recursively,
+ * equivalent to the shell's `mkdir -p` command. This approach is:
+ * - Cross-platform (works identically on all OSes)
+ * - Native to Node.js (no shell commands needed)
+ * - Idempotent (safe to run multiple times)
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} args.0 - Directory path to create
+ * @returns {Promise<void>}
+ */
+async function do_mkd_nodejs(args) {
+  // Validate arguments
+  if (args.length === 0) {
+    console.error('Usage: mkd <directory>');
+    console.error('');
+    console.error('Creates a new directory, including parent directories if needed.');
+    console.error('');
+    console.error('Examples:');
+    console.error('  mkd my-project');
+    console.error('  mkd path/to/nested/directory');
+    console.error('  mkd ~/projects/new-app');
+    process.exit(1);
+  }
+
+  // Get the directory path from arguments
+  // The original bash function used "$@" which takes all arguments,
+  // but typically mkd is used with a single directory path
+  const rawPath = args.join(' ');
+
+  // Expand tilde if present (shells do this automatically, Node.js doesn't)
+  const expandedPath = expandTilde(rawPath);
+
+  // Resolve to absolute path for clearer output
+  const absolutePath = path.resolve(expandedPath);
+
+  // Check if the path already exists
+  if (fs.existsSync(absolutePath)) {
+    // Check if it's a directory or a file
+    const stats = fs.statSync(absolutePath);
+    if (stats.isDirectory()) {
+      // Directory already exists - this is fine (idempotent behavior)
+      console.log(`Directory already exists: ${absolutePath}`);
+      console.log('');
+      console.log(`To navigate there, run: cd "${absolutePath}"`);
+      return;
+    } else {
+      // A file with the same name exists - this is an error
+      console.error(`Error: A file with this name already exists: ${absolutePath}`);
+      console.error('Cannot create a directory with the same name as an existing file.');
+      process.exit(1);
+    }
+  }
+
+  // Create the directory (and all parent directories)
+  // fs.mkdirSync with recursive:true is equivalent to mkdir -p
+  try {
+    fs.mkdirSync(absolutePath, { recursive: true });
+  } catch (error) {
+    // Handle permission errors and other filesystem errors
+    if (error.code === 'EACCES') {
+      console.error(`Error: Permission denied. Cannot create directory: ${absolutePath}`);
+      console.error('You may need to run this command with elevated privileges.');
+    } else if (error.code === 'ENOENT') {
+      console.error(`Error: Invalid path: ${absolutePath}`);
+    } else if (error.code === 'ENOTDIR') {
+      console.error(`Error: A component of the path is not a directory: ${absolutePath}`);
+    } else {
+      console.error(`Error: Failed to create directory: ${error.message}`);
+    }
+    process.exit(1);
+  }
+
+  // Verify the directory was created
+  if (!fs.existsSync(absolutePath)) {
+    console.error(`Error: Directory creation appeared to succeed but directory does not exist.`);
+    process.exit(1);
+  }
+
+  // Success! Print the result
+  // Note: Unlike the original shell function, we cannot change the parent shell's
+  // working directory. We provide instructions instead.
+  console.log(`Created directory: ${absolutePath}`);
+  console.log('');
+  console.log(`To navigate there, run: cd "${absolutePath}"`);
+}
+
+/**
+ * Create directory on macOS.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically on macOS as on other platforms.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_macos(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Create directory on Ubuntu.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically on Linux as on other platforms.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_ubuntu(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Create directory on Raspberry Pi OS.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically on Raspberry Pi OS as on other platforms.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_raspbian(args) {
+  return do_mkd_nodejs(args);
+}
+
 /**
- * Creates a new directory (including parent directories) and
- * outputs the path for shell navigation (e.g., cd $(mkd mydir)).
+ * Create directory on Amazon Linux.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically on Amazon Linux as on other platforms.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_amazon_linux(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Create directory in Windows Command Prompt.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically on Windows as on other platforms. The Node.js fs module
+ * handles Windows path separators automatically.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_cmd(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Create directory in Windows PowerShell.
+ *
+ * Uses the pure Node.js implementation since fs.mkdirSync works
+ * identically across all platforms and shells.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_powershell(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Create directory in Git Bash on Windows.
+ *
+ * Uses the pure Node.js implementation. Git Bash understands both
+ * Unix-style and Windows-style paths, and Node.js handles the conversion.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_mkd_gitbash(args) {
+  return do_mkd_nodejs(args);
+}
+
+/**
+ * Main entry point - detects environment and executes appropriate implementation.
+ *
+ * The "mkd" (make directory) command is a developer convenience tool that:
+ * 1. Creates a new directory, including all parent directories if needed
+ * 2. Provides the cd command to navigate to the new directory
+ *
+ * This replicates the shell function pattern of creating a directory and
+ * immediately entering it, common in developer workflows when starting
+ * new projects or organizing files.
+ *
+ * Note: Unlike the original shell function, this script cannot change the
+ * parent shell's working directory. Node.js scripts run in a subprocess and
+ * cannot affect the parent process's environment. The script outputs the
+ * cd command for the user to run.
+ *
+ * For a true "mkdir and cd" experience, users can use a shell alias:
+ *   alias mkd='function _mkd(){ mkd "$1" && cd "$1"; }; _mkd'
+ * Or use command substitution:
+ *   cd $(mkd --quiet my-dir)  # If --quiet flag were implemented
  *
  * @param {string[]} args - Command line arguments
  * @param {string} args.0 - Directory path to create
  * @returns {Promise<void>}
  */
-async function main(args) {
-  // TODO: Implement mkdir with cd
+async function do_mkd(args) {
+  const platform = os.detect();
+
+  const handlers = {
+    'macos': do_mkd_macos,
+    'ubuntu': do_mkd_ubuntu,
+    'debian': do_mkd_ubuntu,
+    'raspbian': do_mkd_raspbian,
+    'amazon_linux': do_mkd_amazon_linux,
+    'rhel': do_mkd_amazon_linux,
+    'fedora': do_mkd_ubuntu,
+    'linux': do_mkd_ubuntu,
+    'wsl': do_mkd_ubuntu,
+    'cmd': do_mkd_cmd,
+    'windows': do_mkd_cmd,
+    'powershell': do_mkd_powershell,
+    'gitbash': do_mkd_gitbash
+  };
+
+  const handler = handlers[platform.type];
+  if (!handler) {
+    console.error(`Platform '${platform.type}' is not supported for this command.`);
+    console.error('');
+    console.error('Supported platforms:');
+    console.error('  - macOS');
+    console.error('  - Ubuntu, Debian, and other Linux distributions');
+    console.error('  - Raspberry Pi OS');
+    console.error('  - Amazon Linux, RHEL, Fedora');
+    console.error('  - Windows (CMD, PowerShell, Git Bash)');
+    process.exit(1);
+  }
+
+  await handler(args);
 }
 
-module.exports = { main };
+module.exports = {
+  main: do_mkd,
+  do_mkd,
+  do_mkd_nodejs,
+  do_mkd_macos,
+  do_mkd_ubuntu,
+  do_mkd_raspbian,
+  do_mkd_amazon_linux,
+  do_mkd_cmd,
+  do_mkd_powershell,
+  do_mkd_gitbash
+};
 
 if (require.main === module) {
-  main(process.argv.slice(2));
+  do_mkd(process.argv.slice(2));
 }