@fredlackey/devutils 0.0.1 → 0.0.3

package/src/scripts/packages.js

@@ -1,25 +1,330 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Find all package.json files with modification dates.
+ * packages - Find all package.json files with modification dates
+ *
+ * Migrated from legacy dotfiles alias.
+ * Original aliases:
+ *   macOS:  find ./ -type f -name "package.json" -exec stat -f "%Sm %N" -t "%Y-%m-%d %H:%M:%S" {} + | grep -v "node_modules" | sort -n
+ *   Ubuntu: find ./ -type f -name "package.json" -exec stat --format="%Y %n" {} + | grep -v "node_modules" sort -n | awk '{print strftime("%Y-%m-%d %H:%M:%S", $1), $2}'
+ *
+ * This script finds all package.json files recursively in a directory,
+ * excludes those inside node_modules folders, and displays them with their
+ * modification timestamps sorted chronologically. This is useful for:
+ * - Finding when projects were last modified
+ * - Discovering nested projects in a monorepo
+ * - Auditing package.json files across a codebase
+ *
  * @module scripts/packages
  */
 
+const os = require('../utils/common/os');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Recursively finds all files matching a pattern in a directory.
+ * This is a pure Node.js implementation that avoids shell commands.
+ *
+ * @param {string} dir - The directory to search in
+ * @param {string} filename - The filename to look for (e.g., 'package.json')
+ * @param {string[]} excludePaths - Array of path segments to exclude (e.g., ['node_modules'])
+ * @returns {string[]} Array of absolute file paths found
+ */
+function findFilesRecursive(dir, filename, excludePaths = []) {
+  const results = [];
+
+  /**
+   * Internal recursive function that traverses directories.
+   * @param {string} currentDir - Current directory being searched
+   */
+  function traverse(currentDir) {
+    let entries;
+    try {
+      // Read all entries in the current directory
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (err) {
+      // Skip directories we cannot read (permission denied, etc.)
+      // This is common when traversing large file trees
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      // Check if this path should be excluded
+      // We check if any segment of the path matches our exclude list
+      const shouldExclude = excludePaths.some(excludeSegment =>
+        fullPath.split(path.sep).includes(excludeSegment)
+      );
+
+      if (shouldExclude) {
+        continue; // Skip this entry entirely
+      }
+
+      if (entry.isDirectory()) {
+        // Recursively search subdirectories
+        traverse(fullPath);
+      } else if (entry.isFile() && entry.name === filename) {
+        // Found a matching file
+        results.push(fullPath);
+      }
+    }
+  }
+
+  traverse(dir);
+  return results;
+}
+
+/**
+ * Gets the modification time of a file.
+ *
+ * @param {string} filePath - Path to the file
+ * @returns {{ path: string, mtime: Date }|null} Object with path and modification time, or null if error
+ */
+function getFileModTime(filePath) {
+  try {
+    const stats = fs.statSync(filePath);
+    return {
+      path: filePath,
+      mtime: stats.mtime
+    };
+  } catch (err) {
+    // File might have been deleted between finding it and stat'ing it
+    return null;
+  }
+}
+
+/**
+ * Formats a Date object into YYYY-MM-DD HH:MM:SS format.
+ * This matches the format used in the original shell aliases.
+ *
+ * @param {Date} date - The date to format
+ * @returns {string} Formatted date string
+ */
+function formatDate(date) {
+  const year = date.getFullYear();
+  // Months are 0-indexed in JavaScript, so add 1
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
 /**
- * Recursively finds all package.json files in the current directory
- * and displays them with their modification timestamps, sorted by date.
- * Excludes node_modules directories.
+ * Pure Node.js implementation that works on any platform.
+ *
+ * This function finds all package.json files, excludes node_modules,
+ * and displays them sorted by modification time. Because file system
+ * operations are platform-agnostic in Node.js, this single implementation
+ * works identically on macOS, Linux, and Windows.
  *
  * @param {string[]} args - Command line arguments
  * @param {string} [args.0] - Optional path to search (defaults to current directory)
  * @returns {Promise<void>}
  */
-async function main(args) {
-  // TODO: Implement package.json finder
+async function do_packages_nodejs(args) {
+  // Get the search directory from args, or use current working directory
+  const searchDir = args[0] ? path.resolve(args[0]) : process.cwd();
+
+  // Verify the directory exists
+  if (!fs.existsSync(searchDir)) {
+    console.error(`Error: Directory does not exist: ${searchDir}`);
+    process.exit(1);
+  }
+
+  // Verify it's actually a directory
+  const searchDirStats = fs.statSync(searchDir);
+  if (!searchDirStats.isDirectory()) {
+    console.error(`Error: Not a directory: ${searchDir}`);
+    process.exit(1);
+  }
+
+  // Find all package.json files, excluding node_modules directories
+  // This mirrors the original alias behavior: grep -v "node_modules"
+  const packageFiles = findFilesRecursive(searchDir, 'package.json', ['node_modules']);
+
+  if (packageFiles.length === 0) {
+    console.log('No package.json files found.');
+    return;
+  }
+
+  // Get modification times for all found files
+  const filesWithTimes = packageFiles
+    .map(getFileModTime)
+    .filter(item => item !== null); // Remove any files that couldn't be stat'd
+
+  // Sort by modification time (oldest first, like the original 'sort -n')
+  filesWithTimes.sort((a, b) => a.mtime.getTime() - b.mtime.getTime());
+
+  // Display results in the format: "YYYY-MM-DD HH:MM:SS /path/to/package.json"
+  // This matches the original shell alias output format
+  for (const file of filesWithTimes) {
+    const formattedDate = formatDate(file.mtime);
+    // Use relative path from search directory for cleaner output
+    const relativePath = path.relative(searchDir, file.path);
+    // Add ./ prefix to match original alias output
+    const displayPath = relativePath.startsWith('.') ? relativePath : `./${relativePath}`;
+    console.log(`${formattedDate} ${displayPath}`);
+  }
+}
+
+/**
+ * Find package.json files on macOS.
+ * Delegates to the pure Node.js implementation since no macOS-specific
+ * functionality is needed for file searching and listing.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_macos(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files on Ubuntu.
+ * Delegates to the pure Node.js implementation since no Ubuntu-specific
+ * functionality is needed for file searching and listing.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_ubuntu(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files on Raspberry Pi OS.
+ * Delegates to the pure Node.js implementation since no Raspbian-specific
+ * functionality is needed for file searching and listing.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_raspbian(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files on Amazon Linux.
+ * Delegates to the pure Node.js implementation since no Amazon Linux-specific
+ * functionality is needed for file searching and listing.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_amazon_linux(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files on Windows Command Prompt.
+ * Delegates to the pure Node.js implementation since Node.js fs module
+ * handles Windows paths and file operations transparently.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_cmd(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files on Windows PowerShell.
+ * Delegates to the pure Node.js implementation since Node.js fs module
+ * handles Windows paths and file operations transparently.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_powershell(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Find package.json files in Git Bash.
+ * Delegates to the pure Node.js implementation since Node.js fs module
+ * works correctly in Git Bash on Windows.
+ *
+ * @param {string[]} args - Command line arguments
+ * @returns {Promise<void>}
+ */
+async function do_packages_gitbash(args) {
+  return do_packages_nodejs(args);
+}
+
+/**
+ * Main entry point - detects environment and executes appropriate implementation.
+ *
+ * The "packages" command finds all package.json files in a directory tree,
+ * excluding those inside node_modules directories, and displays them sorted
+ * by modification time. This helps developers quickly see:
+ *   - Which projects exist in a directory
+ *   - When each project was last modified
+ *   - Discover nested packages in monorepos
+ *
+ * Usage:
+ *   packages              # Search current directory
+ *   packages /path/to/dir # Search specified directory
+ *
+ * Output format:
+ *   YYYY-MM-DD HH:MM:SS ./path/to/package.json
+ *
+ * @param {string[]} args - Command line arguments
+ * @param {string} [args.0] - Optional path to search
+ * @returns {Promise<void>}
+ */
+async function do_packages(args) {
+  const platform = os.detect();
+
+  const handlers = {
+    'macos': do_packages_macos,
+    'ubuntu': do_packages_ubuntu,
+    'debian': do_packages_ubuntu,
+    'raspbian': do_packages_raspbian,
+    'amazon_linux': do_packages_amazon_linux,
+    'rhel': do_packages_amazon_linux,
+    'fedora': do_packages_ubuntu,
+    'linux': do_packages_ubuntu,
+    'wsl': do_packages_ubuntu,
+    'cmd': do_packages_cmd,
+    'windows': do_packages_cmd,
+    'powershell': do_packages_powershell,
+    'gitbash': do_packages_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_packages,
+  do_packages,
+  do_packages_nodejs,
+  do_packages_macos,
+  do_packages_ubuntu,
+  do_packages_raspbian,
+  do_packages_amazon_linux,
+  do_packages_cmd,
+  do_packages_powershell,
+  do_packages_gitbash
+};
 
 if (require.main === module) {
-  main(process.argv.slice(2));
+  do_packages(process.argv.slice(2));
 }

package/src/scripts/path.js

@@ -1,23 +1,225 @@
 #!/usr/bin/env node
 
 /**
- * @fileoverview Display PATH entries one per line.
+ * path - Display PATH entries one per line
+ *
+ * Migrated from legacy dotfiles alias.
+ * Original: alias path='printf "%b\n" "${PATH//:/\\n}"'
+ *
+ * This script displays each directory in the system PATH environment variable
+ * on a separate line for easier reading. The PATH variable is typically a
+ * long, colon-separated (Unix) or semicolon-separated (Windows) string that
+ * is difficult to read in its raw form.
+ *
+ * This is implemented in pure Node.js because:
+ * - process.env.PATH provides the PATH variable on all platforms
+ * - path.delimiter gives us the platform-specific separator (: or ;)
+ * - Simple string splitting and output require no shell commands
+ *
  * @module scripts/path
  */
 
+const path = require('path');
+const os = require('../utils/common/os');
+
+/**
+ * Pure Node.js implementation that works on any platform.
+ *
+ * This function handles the core logic of parsing and displaying the PATH:
+ * 1. Gets the PATH environment variable from process.env.PATH
+ * 2. Splits it using the platform-appropriate delimiter (: on Unix, ; on Windows)
+ * 3. Prints each path entry on its own line
+ *
+ * The path.delimiter constant automatically uses the correct separator for
+ * the current platform, making this truly cross-platform without any
+ * conditional logic.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_nodejs(args) {
+  // Get the PATH environment variable
+  // On Unix: /usr/bin:/usr/local/bin:/home/user/bin
+  // On Windows: C:\Windows\system32;C:\Windows;C:\Program Files\node
+  const pathEnv = process.env.PATH;
+
+  // Handle edge case: PATH is not set or empty
+  if (!pathEnv) {
+    console.log('PATH environment variable is not set or empty.');
+    return;
+  }
+
+  // Split by the platform-specific delimiter
+  // path.delimiter is ':' on Unix/macOS and ';' on Windows
+  const pathEntries = pathEnv.split(path.delimiter);
+
+  // Print each path entry on its own line
+  // Filter out empty strings that might result from double delimiters (e.g., "::")
+  for (const entry of pathEntries) {
+    if (entry) {
+      console.log(entry);
+    }
+  }
+}
+
+/**
+ * Display PATH entries on macOS.
+ *
+ * macOS uses colon-separated paths like other Unix systems.
+ * Example PATH: /usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_macos(args) {
+  // Pure Node.js handles this perfectly - no macOS-specific code needed
+  return do_path_nodejs(args);
+}
+
+/**
+ * Display PATH entries on Ubuntu.
+ *
+ * Ubuntu uses colon-separated paths like other Unix systems.
+ * Example PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_ubuntu(args) {
+  // Pure Node.js handles this perfectly - no Ubuntu-specific code needed
+  return do_path_nodejs(args);
+}
+
+/**
+ * Display PATH entries on Raspberry Pi OS.
+ *
+ * Raspberry Pi OS (Raspbian) uses colon-separated paths like other Unix systems.
+ * Example PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_raspbian(args) {
+  // Pure Node.js handles this perfectly - no Raspbian-specific code needed
+  return do_path_nodejs(args);
+}
+
+/**
+ * Display PATH entries on Amazon Linux.
+ *
+ * Amazon Linux uses colon-separated paths like other Unix systems.
+ * Example PATH: /usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_amazon_linux(args) {
+  // Pure Node.js handles this perfectly - no Amazon Linux-specific code needed
+  return do_path_nodejs(args);
+}
+
+/**
+ * Display PATH entries on Windows Command Prompt.
+ *
+ * Windows uses semicolon-separated paths.
+ * Example PATH: C:\Windows\system32;C:\Windows;C:\Program Files\nodejs
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_cmd(args) {
+  // Pure Node.js handles this perfectly - path.delimiter is ';' on Windows
+  return do_path_nodejs(args);
+}
+
 /**
- * Outputs each directory in the system PATH environment variable
- * on a separate line for easier reading.
+ * Display PATH entries on Windows PowerShell.
+ *
+ * Windows PowerShell uses the same PATH as Command Prompt (semicolon-separated).
+ * Example PATH: C:\Windows\system32;C:\Windows;C:\Program Files\nodejs
  *
  * @param {string[]} args - Command line arguments (unused)
  * @returns {Promise<void>}
  */
-async function main(args) {
-  // TODO: Implement PATH display
+async function do_path_powershell(args) {
+  // Pure Node.js handles this perfectly - path.delimiter is ';' on Windows
+  return do_path_nodejs(args);
+}
+
+/**
+ * Display PATH entries in Git Bash.
+ *
+ * Git Bash on Windows uses Unix-style colon-separated paths internally,
+ * but process.env.PATH and path.delimiter handle this automatically.
+ * The Node.js path module correctly detects the environment.
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path_gitbash(args) {
+  // Pure Node.js handles this perfectly - works in Git Bash environment
+  return do_path_nodejs(args);
+}
+
+/**
+ * Main entry point - detects environment and executes appropriate implementation.
+ *
+ * The "path" command displays each directory in the PATH environment variable
+ * on its own line, making it easy to see all locations where the shell searches
+ * for executable programs.
+ *
+ * This is useful for:
+ * - Debugging PATH issues (e.g., "why isn't my command found?")
+ * - Understanding the order executables are searched
+ * - Quickly viewing all directories without manual string parsing
+ *
+ * @param {string[]} args - Command line arguments (unused)
+ * @returns {Promise<void>}
+ */
+async function do_path(args) {
+  const platform = os.detect();
+
+  const handlers = {
+    'macos': do_path_macos,
+    'ubuntu': do_path_ubuntu,
+    'debian': do_path_ubuntu,
+    'raspbian': do_path_raspbian,
+    'amazon_linux': do_path_amazon_linux,
+    'rhel': do_path_amazon_linux,
+    'fedora': do_path_ubuntu,
+    'linux': do_path_ubuntu,
+    'wsl': do_path_ubuntu,
+    'cmd': do_path_cmd,
+    'windows': do_path_cmd,
+    'powershell': do_path_powershell,
+    'gitbash': do_path_gitbash
+  };
+
+  const handler = handlers[platform.type];
+  if (!handler) {
+    // Even for unknown platforms, the Node.js implementation will work
+    // because path.delimiter is available on all Node.js platforms
+    console.log(`Note: Platform '${platform.type}' is not explicitly supported, using default implementation.`);
+    await do_path_nodejs(args);
+    return;
+  }
+
+  await handler(args);
 }
 
-module.exports = { main };
+module.exports = {
+  main: do_path,
+  do_path,
+  do_path_nodejs,
+  do_path_macos,
+  do_path_ubuntu,
+  do_path_raspbian,
+  do_path_amazon_linux,
+  do_path_cmd,
+  do_path_powershell,
+  do_path_gitbash
+};
 
 if (require.main === module) {
-  main(process.argv.slice(2));
+  do_path(process.argv.slice(2));
 }