@fredlackey/devutils 0.0.18 → 0.1.0

package/src/scripts/q.js

@@ -1,305 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * q - Exit the current shell session (quick exit)
- *
- * Migrated from legacy dotfiles alias.
- * Original: alias q="exit"
- *
- * IMPORTANT LIMITATION:
- * The original `q` alias worked because shell aliases run in the same process
- * as the shell itself. When you type `q` and it runs `exit`, the shell exits.
- *
- * However, this Node.js script runs as a CHILD PROCESS of your shell. When we
- * call `process.exit()` here, it only exits THIS script's process - not your
- * parent shell. There is no cross-platform way for a child process to force
- * its parent process to terminate.
- *
- * WORKAROUND OPTIONS:
- *
- * 1. Use the native shell command directly:
- *    Just type `exit` in your terminal.
- *
- * 2. Create a shell alias (recommended for true `q` behavior):
- *    In your ~/.bashrc or ~/.zshrc:
- *      alias q="exit"
- *
- *    In PowerShell $PROFILE:
- *      function q { exit }
- *
- * 3. Source this script's output (advanced):
- *    eval "$(q)"  # This would work if the script printed "exit"
- *
- * This script provides informative guidance to users about this limitation.
- *
- * @module scripts/q
- */
-
-const os = require('../utils/common/os');
-
-/**
- * Pure Node.js implementation that explains the exit limitation.
- *
- * Since exiting the parent shell is not possible from a child process,
- * this function prints helpful information to the user.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_nodejs(args) {
-  // Check if user passed --help or -h
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    return;
-  }
-
-  // Check if user wants shell-sourceable output (--eval or -e flag)
-  // Usage: eval "$(q --eval)" or eval "$(q -e)"
-  if (args.includes('--eval') || args.includes('-e')) {
-    // Print the exit command so it can be sourced/evaled by the parent shell
-    console.log('exit');
-    return;
-  }
-
-  // Default behavior: inform the user about the limitation
-  console.log('To exit your shell, type: exit');
-  console.log('');
-  console.log('Note: The `q` command cannot exit your shell directly because');
-  console.log('it runs as a child process. For true `q` behavior, add this');
-  console.log('alias to your shell config:');
-  console.log('');
-
-  const platform = os.detect();
-
-  // Provide shell-specific guidance
-  if (platform.type === 'windows' || platform.type === 'powershell') {
-    console.log('  PowerShell (add to $PROFILE):');
-    console.log('    function q { exit }');
-  } else if (platform.type === 'cmd') {
-    console.log('  CMD (create a doskey alias or batch file):');
-    console.log('    doskey q=exit');
-  } else {
-    // Unix-like systems (macOS, Linux, Git Bash)
-    console.log('  Bash/Zsh (add to ~/.bashrc or ~/.zshrc):');
-    console.log('    alias q="exit"');
-  }
-
-  console.log('');
-  console.log('Alternatively, use: eval "$(q --eval)" to exit immediately.');
-}
-
-/**
- * Prints help information about the q command.
- *
- * @returns {void}
- */
-function printHelp() {
-  console.log('q - Quick exit command');
-  console.log('');
-  console.log('Usage:');
-  console.log('  q              Show exit instructions');
-  console.log('  q --eval       Print "exit" for shell sourcing');
-  console.log('  q -e           Same as --eval');
-  console.log('  q --help       Show this help message');
-  console.log('  q -h           Same as --help');
-  console.log('');
-  console.log('Examples:');
-  console.log('  # Show instructions');
-  console.log('  q');
-  console.log('');
-  console.log('  # Exit shell immediately (Bash/Zsh):');
-  console.log('  eval "$(q --eval)"');
-  console.log('');
-  console.log('  # Exit shell immediately (PowerShell):');
-  console.log('  Invoke-Expression (q --eval)');
-  console.log('');
-  console.log('Note: For true `q` behavior, create a shell alias instead.');
-  console.log('This script cannot exit the parent shell directly because');
-  console.log('it runs as a child process.');
-}
-
-/**
- * Exit guidance on macOS.
- *
- * On macOS, the default shell is Zsh (since Catalina) or Bash (older versions).
- * Both support the `alias q="exit"` syntax.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_macos(args) {
-  return do_q_nodejs(args);
-}
-
-/**
- * Exit guidance on Ubuntu.
- *
- * Ubuntu uses Bash by default. The `alias q="exit"` syntax works.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_ubuntu(args) {
-  return do_q_nodejs(args);
-}
-
-/**
- * Exit guidance on Raspberry Pi OS.
- *
- * Raspberry Pi OS uses Bash by default. The `alias q="exit"` syntax works.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_raspbian(args) {
-  return do_q_nodejs(args);
-}
-
-/**
- * Exit guidance on Amazon Linux.
- *
- * Amazon Linux uses Bash by default. The `alias q="exit"` syntax works.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_amazon_linux(args) {
-  return do_q_nodejs(args);
-}
-
-/**
- * Exit guidance in Windows Command Prompt.
- *
- * CMD supports doskey macros or batch files for creating aliases.
- * The `exit` command itself works directly in CMD.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_cmd(args) {
-  // Check for --eval flag
-  if (args.includes('--eval') || args.includes('-e')) {
-    console.log('exit');
-    return;
-  }
-
-  // Check for --help flag
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    return;
-  }
-
-  console.log('To exit your shell, type: exit');
-  console.log('');
-  console.log('Note: The `q` command cannot exit your shell directly because');
-  console.log('it runs as a child process. For true `q` behavior, you can:');
-  console.log('');
-  console.log('  Create a doskey macro (temporary, for current session):');
-  console.log('    doskey q=exit');
-  console.log('');
-  console.log('  Or create a q.bat file in a PATH directory:');
-  console.log('    @echo off');
-  console.log('    exit');
-}
-
-/**
- * Exit guidance in Windows PowerShell.
- *
- * PowerShell supports functions for creating aliases to commands with arguments.
- * The `exit` command works directly in PowerShell.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_powershell(args) {
-  // Check for --eval flag
-  if (args.includes('--eval') || args.includes('-e')) {
-    console.log('exit');
-    return;
-  }
-
-  // Check for --help flag
-  if (args.includes('--help') || args.includes('-h')) {
-    printHelp();
-    return;
-  }
-
-  console.log('To exit your shell, type: exit');
-  console.log('');
-  console.log('Note: The `q` command cannot exit your shell directly because');
-  console.log('it runs as a child process. For true `q` behavior, add this');
-  console.log('to your PowerShell profile ($PROFILE):');
-  console.log('');
-  console.log('  function q { exit }');
-  console.log('');
-  console.log('Alternatively, use: Invoke-Expression (q --eval)');
-}
-
-/**
- * Exit guidance in Git Bash.
- *
- * Git Bash is a Bash shell on Windows, so `alias q="exit"` works.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q_gitbash(args) {
-  return do_q_nodejs(args);
-}
-
-/**
- * Main entry point - detects environment and executes appropriate implementation.
- *
- * The "q" command is a quick shorthand for "exit" to leave the current shell.
- * Due to process isolation, this script cannot directly exit the parent shell,
- * so it provides guidance on how to achieve the desired behavior.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_q(args) {
-  const platform = os.detect();
-
-  const handlers = {
-    'macos': do_q_macos,
-    'ubuntu': do_q_ubuntu,
-    'debian': do_q_ubuntu,
-    'raspbian': do_q_raspbian,
-    'amazon_linux': do_q_amazon_linux,
-    'rhel': do_q_amazon_linux,
-    'fedora': do_q_ubuntu,
-    'linux': do_q_ubuntu,
-    'wsl': do_q_ubuntu,
-    'cmd': do_q_cmd,
-    'windows': do_q_cmd,
-    'powershell': do_q_powershell,
-    'gitbash': do_q_gitbash
-  };
-
-  const handler = handlers[platform.type];
-  if (!handler) {
-    // Fallback to generic Node.js implementation
-    // This ensures the script works on unknown platforms too
-    await do_q_nodejs(args);
-    return;
-  }
-
-  await handler(args);
-}
-
-module.exports = {
-  main: do_q,
-  do_q,
-  do_q_nodejs,
-  do_q_macos,
-  do_q_ubuntu,
-  do_q_raspbian,
-  do_q_amazon_linux,
-  do_q_cmd,
-  do_q_powershell,
-  do_q_gitbash
-};
-
-if (require.main === module) {
-  do_q(process.argv.slice(2));
-}

package/src/scripts/refresh-files.js

@@ -1,394 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * refresh-files - Copy matching files from source to target directory
- *
- * Migrated from legacy dotfiles alias.
- * Original bash function (see research/dotfiles/src/shell/bash_functions):
- *
- *   refresh-files SOURCE_FOLDER [TARGET_FOLDER]
- *
- *   Compares files in the target directory with a source directory and copies
- *   over files that exist in both locations from the source. Skips node_modules
- *   and bower_components directories.
- *
- * This script compares files in a target directory with a source directory
- * and copies over files that exist in BOTH locations from the source.
- * This is useful for:
- * - Refreshing vendor source files from a stable/reference project
- * - Syncing configuration files with a known-good copy
- * - Keeping critical files in sync with a master copy
- *
- * The script does NOT add new files to the target. It only updates files
- * that already exist in the target directory if they also exist in the source.
- *
- * @module scripts/refresh-files
- */
-
-const os = require('../utils/common/os');
-const fs = require('fs');
-const path = require('path');
-
-/**
- * Directories to skip when walking the target directory tree.
- * These are typically large dependency directories that should not be refreshed.
- */
-const SKIP_DIRECTORIES = ['node_modules', 'bower_components', '.git'];
-
-/**
- * Recursively find all files in a directory, skipping certain directories.
- * Returns absolute paths to all files found.
- *
- * @param {string} dirPath - Absolute path to the directory to search
- * @param {string[]} skipDirs - Array of directory names to skip
- * @returns {string[]} Array of absolute file paths
- */
-function findFilesRecursively(dirPath, skipDirs) {
-  const results = [];
-
-  /**
-   * Inner recursive function to walk the directory tree.
-   * @param {string} currentDir - Current directory being examined
-   */
-  function walk(currentDir) {
-    let entries;
-
-    try {
-      entries = fs.readdirSync(currentDir, { withFileTypes: true });
-    } catch (err) {
-      // Cannot read directory (permission denied, etc.) - skip it
-      return;
-    }
-
-    for (const entry of entries) {
-      const fullPath = path.join(currentDir, entry.name);
-
-      if (entry.isDirectory()) {
-        // Skip directories in our skip list
-        if (skipDirs.includes(entry.name)) {
-          continue;
-        }
-        // Recurse into other directories
-        walk(fullPath);
-      } else if (entry.isFile()) {
-        // Add file to results
-        results.push(fullPath);
-      }
-      // Skip symlinks and other special entries
-    }
-  }
-
-  walk(dirPath);
-  return results;
-}
-
-/**
- * Copy a file from source to destination, creating parent directories if needed.
- * This function overwrites the destination file if it exists.
- *
- * @param {string} sourcePath - Absolute path to the source file
- * @param {string} destPath - Absolute path to the destination file
- * @returns {boolean} True if copy succeeded, false otherwise
- */
-function copyFile(sourcePath, destPath) {
-  try {
-    // Read the source file
-    const content = fs.readFileSync(sourcePath);
-    // Write to the destination (this overwrites if exists)
-    fs.writeFileSync(destPath, content);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Check if a file exists at the given path.
- *
- * @param {string} filePath - Absolute path to check
- * @returns {boolean} True if file exists and is a regular file
- */
-function fileExists(filePath) {
-  try {
-    const stats = fs.statSync(filePath);
-    return stats.isFile();
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Check if a directory exists at the given path.
- *
- * @param {string} dirPath - Absolute path to check
- * @returns {boolean} True if directory exists
- */
-function directoryExists(dirPath) {
-  try {
-    const stats = fs.statSync(dirPath);
-    return stats.isDirectory();
-  } catch (err) {
-    return false;
-  }
-}
-
-/**
- * Pure Node.js implementation that works on any platform.
- * This function contains the cross-platform logic using only Node.js APIs.
- *
- * The function walks through all files in the target directory, and for each
- * file it checks if a corresponding file exists in the source directory
- * (at the same relative path). If it does, the source file is copied over
- * the target file, effectively "refreshing" it.
- *
- * @param {string[]} args - Command line arguments
- * @param {string} args[0] - Source folder path (required)
- * @param {string} [args[1]] - Target folder path (defaults to current directory)
- * @returns {Promise<void>}
- */
-async function do_refresh_files_nodejs(args) {
-  // Parse arguments
-  const sourceArg = args[0];
-  const targetArg = args[1];
-
-  // Validate source argument is provided
-  if (!sourceArg) {
-    console.error('Error: Source folder not supplied.');
-    console.error('');
-    console.error('USAGE: refresh-files SOURCE_FOLDER [TARGET_FOLDER]');
-    console.error('');
-    console.error('This command compares files in the target directory with the source');
-    console.error('directory and copies over files that exist in both locations from');
-    console.error('the source. Files are only updated, never added or removed.');
-    console.error('');
-    console.error('Arguments:');
-    console.error('  SOURCE_FOLDER  Path to the reference/stable project');
-    console.error('  TARGET_FOLDER  Path to update (defaults to current directory)');
-    process.exit(1);
-  }
-
-  // Resolve paths to absolute paths
-  const sourcePath = path.resolve(sourceArg);
-  const targetPath = targetArg ? path.resolve(targetArg) : process.cwd();
-
-  // Validate source directory exists
-  if (!directoryExists(sourcePath)) {
-    console.error(`Error: Source folder does not exist: ${sourcePath}`);
-    process.exit(1);
-  }
-
-  // Validate target directory exists
-  if (!directoryExists(targetPath)) {
-    console.error(`Error: Target folder does not exist: ${targetPath}`);
-    process.exit(1);
-  }
-
-  // Print operation header
-  console.log('Refreshing files...');
-  console.log(`FROM: ${sourcePath}`);
-  console.log(`TO  : ${targetPath}`);
-  console.log('-----');
-
-  // Find all files in the target directory (excluding node_modules, etc.)
-  const targetFiles = findFilesRecursively(targetPath, SKIP_DIRECTORIES);
-
-  // Track statistics
-  let refreshedCount = 0;
-  let failedCount = 0;
-  const failedFiles = [];
-
-  // For each file in target, check if it exists in source and copy if so
-  for (const targetFile of targetFiles) {
-    // Calculate the relative path from target root
-    const relativePath = path.relative(targetPath, targetFile);
-
-    // Construct the corresponding source file path
-    const sourceFile = path.join(sourcePath, relativePath);
-
-    // Check if this file exists in the source directory
-    if (fileExists(sourceFile)) {
-      // File exists in both locations - copy from source to target
-      const success = copyFile(sourceFile, targetFile);
-
-      if (success) {
-        // Use forward slashes for display (matches original bash output)
-        const displayPath = relativePath.split(path.sep).join('/');
-        console.log(displayPath);
-        refreshedCount++;
-      } else {
-        failedCount++;
-        failedFiles.push(relativePath);
-      }
-    }
-    // If file doesn't exist in source, we simply skip it (no output)
-  }
-
-  // Print summary
-  console.log('-----');
-  console.log(`Files refreshed: ${refreshedCount}`);
-
-  // Report any failures
-  if (failedCount > 0) {
-    console.log('');
-    console.log(`Failed to refresh ${failedCount} file${failedCount === 1 ? '' : 's'}:`);
-    for (const file of failedFiles) {
-      console.log(`  - ${file}`);
-    }
-    console.log('');
-    console.log('Tip: Check file permissions on the above files.');
-  }
-}
-
-/**
- * Refresh files from source to target directory on macOS.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_macos(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Ubuntu.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_ubuntu(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Raspberry Pi OS.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_raspbian(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Amazon Linux.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_amazon_linux(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Windows Command Prompt.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_cmd(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Windows PowerShell.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_powershell(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Refresh files from source to target directory on Git Bash.
- * Uses the pure Node.js implementation since file operations work identically.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files_gitbash(args) {
-  return do_refresh_files_nodejs(args);
-}
-
-/**
- * Main entry point - detects environment and executes appropriate implementation.
- *
- * Compares files in the target directory with a source directory and copies
- * over files that exist in BOTH locations from the source. This is useful for
- * refreshing project files from a stable/reference copy.
- *
- * Key behavior:
- * - Only updates files that already exist in the target
- * - Does NOT add new files to the target
- * - Does NOT remove files from the target
- * - Skips node_modules, bower_components, and .git directories
- *
- * Usage:
- *   refresh-files /path/to/source               # Refresh current directory
- *   refresh-files /path/to/source /path/to/target  # Refresh specific directory
- *
- * Example scenario:
- *   You have a "golden" project with known-good configuration files.
- *   You want to update your working project with those configurations.
- *   Running refresh-files will copy only files that exist in both places.
- *
- * @param {string[]} args - Command line arguments
- * @returns {Promise<void>}
- */
-async function do_refresh_files(args) {
-  const platform = os.detect();
-
-  const handlers = {
-    'macos': do_refresh_files_macos,
-    'ubuntu': do_refresh_files_ubuntu,
-    'debian': do_refresh_files_ubuntu,
-    'raspbian': do_refresh_files_raspbian,
-    'amazon_linux': do_refresh_files_amazon_linux,
-    'rhel': do_refresh_files_amazon_linux,
-    'fedora': do_refresh_files_ubuntu,
-    'linux': do_refresh_files_ubuntu,
-    'wsl': do_refresh_files_ubuntu,
-    'cmd': do_refresh_files_cmd,
-    'windows': do_refresh_files_cmd,
-    'powershell': do_refresh_files_powershell,
-    'gitbash': do_refresh_files_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: do_refresh_files,
-  do_refresh_files,
-  do_refresh_files_nodejs,
-  do_refresh_files_macos,
-  do_refresh_files_ubuntu,
-  do_refresh_files_raspbian,
-  do_refresh_files_amazon_linux,
-  do_refresh_files_cmd,
-  do_refresh_files_powershell,
-  do_refresh_files_gitbash
-};
-
-if (require.main === module) {
-  do_refresh_files(process.argv.slice(2));
-}