@tertium/hlpr 0.6.0 → 0.6.1

package/bin/commands/file/rename/README.md

@@ -0,0 +1,225 @@
+# Rename Command
+
+Recursively rename files and folders according to a specific case style.
+
+## Usage
+
+```bash
+hlpr file rename <directory> <style> [--dry|-n] [--no-update-content]
+```
+
+### Arguments
+
+- `<directory>` - The root directory to recursively process
+- `<style>` - The target case style (see Supported Styles below)
+- `--dry` or `-n` - Optional dry-run mode (preview changes without applying)
+- `--no-update-content` - Skip updating import/require statements in files (content updates are enabled by default)
+
+## Supported Styles
+
+| Style | Description | Example |
+|-------|-------------|---------|
+| `title_underscore` | Title case with underscores | `File_Name` |
+| `pascal_underscore` | Pascal-style with underscores (alias `title_underscore`) | `File_Name` |
+| `snake` | Lowercase with underscores | `file_name` |
+| `kebab` | Lowercase with hyphens | `file-name` |
+| `camel` | Lowercase first word, capitalized rest | `fileName` |
+| `pascal` | All words capitalized, no separators | `FileName` |
+| `upper` | Uppercase with underscores | `FILE_NAME` |
+| `lower` | Lowercase with underscores | `file_name` |
+
+## Examples
+
+### Dry Run (Preview Changes)
+
+```bash
+# Preview renaming all files/folders to kebab-case
+hlpr file rename ./my-project kebab --dry
+
+# Preview renaming with short flag
+hlpr file rename ./src snake -n
+```
+
+### Apply Changes
+
+```bash
+# Rename all files/folders to kebab-case
+hlpr file rename ./my-project kebab
+
+# Rename to PascalCase
+hlpr file rename ./docs pascal
+
+# Rename current directory
+hlpr file rename . snake
+hlpr rename . snake
+```
+
+## Features
+
+### ✅ Automatic Content Updates
+
+**NEW:** By default, the rename command now automatically updates import and require statements in your code files when files are renamed!
+
+The tool intelligently detects and updates **all text-based files** by analyzing file content (not just extensions). This includes:
+
+- Source code: `.js`, `.ts`, `.jsx`, `.tsx`, `.py`, `.rb`, `.go`, `.rs`, etc.
+- Config files: `.json`, `.yml`, `.yaml`, `.toml`, `.xml`, `.ini`, etc.
+- Documentation: `.md`, `.txt`, `.rst`, etc.
+- Shell scripts: `.sh`, `.bash`, `.zsh`, etc.
+- And any other text file format!
+
+Binary files (images, executables, etc.) are automatically skipped.
+
+Example:
+
+```javascript
+// Before renaming from kebab-case to snake_case:
+import { helper } from './my-utils'
+const x = require('./my-utils')
+
+// After running: hlpr file rename . snake
+import { helper } from './my_utils'
+const x = require('./my_utils')
+```
+
+The feature supports:
+
+- Single quotes, double quotes, and backticks
+- Relative paths (`./`, `../`)
+- Files with and without extensions in import statements
+- Both ES6 imports and CommonJS require statements
+
+To disable this feature, use the `--no-update-content` flag.
+
+### ✅ Recursive Processing
+
+The command walks through all subdirectories, renaming:
+
+1. Files first (so they don't interfere with directory renames)
+2. Directories after processing their contents
+3. Updates file content references after renaming (unless disabled)
+
+### ✅ Extension Preservation
+
+File extensions are preserved. Only the base name is transformed:
+
+- `file-name.md` → `file_name.md` (snake case)
+- `MyComponent.tsx` → `my-component.tsx` (kebab case)
+
+### ✅ Leading Dot Files
+
+Files starting with a dot (e.g., `.gitignore`, `.env`) are handled specially:
+
+- The leading dot is preserved
+- The rest of the name is transformed
+- `.gitIgnore` → `.git-ignore` (kebab case)
+
+### ✅ Case-Only Renames (Windows)
+
+Windows filesystems are case-insensitive, so renaming `File.txt` to `file.txt` requires special handling. The command uses a temporary file strategy to handle this correctly.
+
+### ✅ Conflict Resolution
+
+If a renamed file would conflict with an existing file, the command automatically adds a `_N` suffix:
+
+- If `file-name.txt` → `file_name.txt` already exists
+- The new file becomes `file_name_1.txt`
+
+### ✅ Dry-Run Mode
+
+Use `--dry` or `-n` to preview all changes before applying them:
+
+```bash
+hlpr file rename ./src kebab --dry
+```
+
+Output:
+
+```text
+Dry run - would rename 3 items:
+  src/myFile.ts → src/my-file.ts
+  src/anotherFile.ts → src/another-file.ts
+  src/someFolder → src/some-folder
+```
+
+## TypeScript API
+
+The command can also be used programmatically:
+
+```typescript
+import { renameRecursive, transformBasename } from './commands/rename/rename.js'
+
+// Transform a single basename
+const newName = transformBasename('MyFileName', 'kebab')
+// Returns: 'my-file-name'
+
+// Recursively rename with dry-run
+const changes = await renameRecursive('./my-project', 'snake', { dryRun: true })
+// Returns: [{ from: '...', to: '...' }, ...]
+
+// Apply changes with content updates (default)
+await renameRecursive('./my-project', 'kebab')
+
+// Apply changes without updating file contents
+await renameRecursive('./my-project', 'kebab', { updateContent: false })
+
+// Combine options
+await renameRecursive('./my-project', 'snake', {
+  dryRun: false,
+  updateContent: true
+})
+```
+
+## Technical Details
+
+### Word Splitting
+
+The command intelligently splits filenames into words by:
+
+1. Splitting on non-alphanumeric characters (hyphens, underscores, spaces, etc.)
+2. Splitting on CamelCase boundaries (`myFileName` → `my`, `File`, `Name`)
+3. Preserving Unicode letters and numbers
+
+### Transformation Algorithm
+
+1. Walk directory tree recursively
+2. For each file:
+   - Extract basename (without extension)
+   - Transform basename according to style
+   - Append original extension
+   - Rename file (handling case-only renames and conflicts)
+3. For each directory (after processing contents):
+   - Transform directory name according to style
+   - Rename directory (handling case-only renames and conflicts)
+
+### Error Handling
+
+- If a rename fails, the command attempts to revert temporary changes
+- All errors are logged to stderr
+- The command exits with code 1 on failure
+
+## Limitations
+
+- Files and directories must be accessible (proper permissions)
+- Very long paths (>260 characters on Windows) may fail
+- Symlinks are not followed (treated as regular files/directories)
+
+## Examples by Style
+
+Starting with: `MyTestFile-name_Example.txt`
+
+| Style | Result |
+|-------|--------|
+| `title_underscore` | `My_Test_File_Name_Example.txt` |
+| `snake` | `my_test_file_name_example.txt` |
+| `kebab` | `my-test-file-name-example.txt` |
+| `camel` | `myTestFileNameExample.txt` |
+| `pascal` | `MyTestFileNameExample.txt` |
+| `upper` | `MY_TEST_FILE_NAME_EXAMPLE.txt` |
+| `lower` | `my_test_file_name_example.txt` |
+
+## See Also
+
+- [Main hlpr README](../../README.md)
+- [TypeScript Implementation](./rename.ts)
+- [Tests](./rename.test.ts)

package/bin/commands/git/README.md

@@ -0,0 +1,129 @@
+# Git Commands
+
+Helpful git utilities for common development workflows.
+
+## Platform Support
+
+All Git commands work on:
+
+- ✅ **Linux** - Fully supported
+- ✅ **macOS** - Fully supported
+- ✅ **Windows** - Requires Git for Windows (includes Git Bash)
+
+---
+
+## fodd
+
+Fetch and update develop branch from origin.
+
+**Usage:**
+```bash
+hlpr git fodd
+```
+
+**What it does:**
+- Fetches the `develop` branch from origin
+- Updates your local `develop` branch to match the remote
+
+**When to use:**
+- Before starting work to ensure you have the latest develop branch
+- To sync your local develop with the remote
+
+**Command:**
+```bash
+git fetch origin develop:develop
+```
+
+---
+
+## precommit
+
+Run build and stage binaries before commit.
+
+**Usage:**
+```bash
+hlpr git precommit
+```
+
+**What it does:**
+1. Runs `bun run build` to compile your project
+2. Stages the `bin/` directory for commit
+
+**When to use:**
+- Before committing changes to ensure binaries are up-to-date
+- As a git pre-commit hook to automate the process
+
+**Example workflow:**
+```bash
+# Make changes to source files
+hlpr git precommit  # Build and stage bin/
+git commit -m "feat: add new feature"
+```
+
+---
+
+## switch-clean
+
+Safely switch to a target branch and delete the previous branch (both local and remote).
+
+**Usage:**
+```bash
+hlpr git switch-clean <target-branch>
+```
+
+**What it does:**
+
+1. **Validates current state**
+   - Checks you're on a branch (not detached HEAD)
+   - Ensures you're not already on the target branch
+   - Verifies there are no uncommitted changes
+
+2. **Checks for unpushed commits**
+   - Fails if current branch has commits that haven't been pushed
+   - Prevents accidental loss of work
+
+3. **Fetches target branch**
+   - Runs `git fetch origin <target-branch>:<target-branch>`
+   - Updates the target branch to match remote
+
+4. **Switches to target branch**
+   - Checks out the target branch
+
+5. **Deletes previous branch**
+   - Deletes local branch: `git branch -d <old-branch>`
+   - Deletes remote branch (if exists): `git push origin --delete <old-branch>`
+
+**Safety Features:**
+
+- ✅ **Uncommitted changes check** - Prevents switching if you have uncommitted work
+- ✅ **Unpushed commits check** - Ensures all work is pushed before deletion
+- ✅ **Remote existence check** - Only deletes remote branch if it exists
+- ✅ **Safe branch deletion** - Uses `git branch -d` (not `-D`), refuses to delete unmerged branches
+
+**Examples:**
+
+```bash
+# Switch from feature branch to develop and clean up
+hlpr git switch-clean develop
+# ✓ Switched to 'develop' and deleted 'feature/add-auth' (local & remote)
+
+# Switch to main
+hlpr git switch-clean main
+# ✓ Switched to 'main' and deleted 'develop' (local only)
+```
+
+**Error Handling:**
+
+The command will fail and exit if:
+
+- No target branch is specified
+- Not currently on a branch (detached HEAD)
+- Already on the target branch
+- There are uncommitted changes
+- Current branch has unpushed commits
+- Target branch doesn't exist on remote
+
+**Solution:**
+- Commit or stash uncommitted changes
+- Push unpushed commits: `git push origin <branch>`
+- Ensure target branch exists on remote

package/bin/commands/hello/README.md

@@ -0,0 +1,35 @@
+# Hello Commands
+
+Example/demo commands for testing the hlpr CLI tool.
+
+## Platform Support
+
+- ✅ **Linux** - Fully supported
+- ✅ **macOS** - Fully supported
+- ✅ **Windows** - Requires Git Bash or WSL
+
+## world
+
+Print a personalized hello world message.
+
+### Usage
+
+```bash
+hlpr hello world
+```
+
+The command will prompt you for a name and then print a personalized greeting.
+
+### Example
+
+```bash
+$ hlpr hello world
+Enter name: Alice
+Hello World, Alice
+```
+
+### Variables
+
+- `name` - Your name (prompted during execution)
+
+This command demonstrates the variable substitution feature of hlpr, where `{{name}}` in the script is replaced with user input.

package/bin/commands/help/README.md

@@ -0,0 +1,55 @@
+# Help Command
+
+Displays help information about available commands in the hlpr CLI tool.
+
+## Usage
+
+```bash
+hlpr help
+# or
+hlpr --help
+# or
+hlpr -h
+# or just
+hlpr
+```
+
+## Description
+
+The help command automatically discovers all available commands in the `commands/` directory and displays them in an organized format. It shows:
+
+- Command categories (e.g., file, git, ssh, nvm)
+- Command names and full usage
+- Command type (TypeScript or Shell)
+- Command descriptions (when available)
+- Usage examples
+
+## Features
+
+- Auto-discovers commands from the commands directory
+- Groups commands by category
+- Shows command types (TypeScript or Shell scripts)
+- Extracts descriptions from:
+  - `@description` comments in source files
+  - README.md files in command directories
+- Displays formatted help with usage examples
+
+## Examples
+
+```bash
+# Show all available commands
+hlpr help
+
+# If no command is provided, help is shown automatically
+hlpr
+```
+
+## Output
+
+The help command displays:
+
+1. **Header** - Tool name and version
+2. **Usage** - Basic syntax
+3. **Options** - Available flags (-f, -v, help)
+4. **Available Commands** - Grouped by category with descriptions
+5. **Examples** - Common usage patterns

package/bin/commands/nvm/README.md

@@ -0,0 +1,90 @@
+# NVM Commands
+
+Node Version Manager (nvm) utility commands.
+
+## install
+
+Install Node Version Manager (nvm).
+
+### Usage
+
+```bash
+hlpr nvm install
+```
+
+### Platform Support
+
+- ✅ **Linux** - Fully supported
+- ✅ **macOS** - Fully supported
+- ⚠️ **Windows** - Requires Git Bash or WSL (Windows Subsystem for Linux)
+  - **Alternative for Windows**: Use [nvm-windows](https://github.com/coreybutler/nvm-windows) instead
+
+### What it does
+
+Downloads and installs nvm from the official repository using the installation script:
+
+```bash
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+```
+
+### Post-installation
+
+After installation, you may need to:
+
+1. Close and reopen your terminal
+2. Or source your shell profile:
+
+   ```bash
+   source ~/.bashrc  # or ~/.zshrc, ~/.bash_profile, etc.
+   ```
+
+### Verify installation
+
+```bash
+nvm --version
+```
+
+## lts
+
+Install and use the latest Node.js LTS (Long Term Support) version.
+
+### Platform Support (lts)
+
+Same as `install` command - requires nvm to be installed.
+
+### Usage
+
+```bash
+hlpr nvm lts
+```
+
+### What it does (lts)
+
+1. Downloads and installs the latest LTS version of Node.js
+2. Switches to use the newly installed LTS version
+
+Equivalent to running:
+
+```bash
+nvm install --lts
+nvm use --lts
+```
+
+### Example
+
+```bash
+$ hlpr nvm lts
+Downloading and installing node v20.11.0...
+Now using node v20.11.0 (npm v10.2.4)
+```
+
+### Prerequisites
+
+- nvm must be installed first (use `hlpr nvm install`)
+
+### Verify (lts)
+
+```bash
+node --version  # Should show the LTS version
+npm --version   # npm comes with Node.js
+```

package/bin/commands/process/kill-port/README.md

@@ -0,0 +1,49 @@
+# kill-port
+
+Kill process(es) running on a specified port. Supports both Windows and Linux/macOS.
+
+## Usage
+
+```bash
+hlpr process kill-port <port> [options]
+```
+
+## Arguments
+
+- `port` - Port number (1-65535)
+
+## Options
+
+- `-f, --force` - Force kill (SIGKILL on Linux, /F on Windows)
+- `-v, --verbose` - Show verbose output
+- `-h, --help` - Show help message
+
+## Examples
+
+```bash
+# Kill process on port 3000
+hlpr process kill-port 3000
+
+# Force kill with verbose output
+hlpr process kill-port 8080 --force --verbose
+
+# Kill process on port 5432
+hlpr process kill-port 5432 -v
+```
+
+## Platform Support
+
+### Windows
+- Uses `netstat -ano` to find processes
+- Uses `taskkill` to kill processes
+- `-f/--force` flag uses `/F` switch (force termination)
+
+### Linux/macOS
+- Uses `lsof` (preferred) or `netstat` to find processes
+- Uses `kill` command to terminate processes
+- `-f/--force` flag sends SIGKILL instead of SIGTERM
+
+## Exit Codes
+
+- `0` - Success (all processes killed or no processes found)
+- `1` - Failure (some processes could not be killed)

package/bin/commands/process/list-port/README.md

@@ -0,0 +1,58 @@
+# list-port
+
+List process(es) running on a specified port. Supports both Windows and Linux/macOS.
+
+## Usage
+
+```bash
+hlpr process list-port <port> [options]
+```
+
+## Arguments
+
+- `port` - Port number (1-65535)
+
+## Options
+
+- `-v, --verbose` - Show verbose output
+- `-h, --help` - Show help message
+
+## Examples
+
+```bash
+# List processes on port 3000
+hlpr process list-port 3000
+
+# List with verbose output
+hlpr process list-port 8080 -v
+
+# List processes on port 5432
+hlpr process list-port 5432
+```
+
+## Output Format
+
+Displays a table with:
+- **PID** - Process ID
+- **STATE** - Connection state (LISTENING, ESTABLISHED, etc.)
+- **COMMAND** - Process name/command
+
+## Platform Support
+
+### Windows
+- Uses `netstat -ano` to find processes
+- Uses `tasklist` to get process names
+- Shows PID, state, and command
+
+### Linux/macOS
+- Uses `lsof` (preferred) or `netstat` (fallback) to find processes
+- Shows PID, state, and command name
+
+## Exit Codes
+
+- `0` - Success (processes found)
+- `1` - No processes found or error
+
+## See Also
+
+- `hlpr process kill-port` - Kill processes on a port

package/bin/commands/ssh/README.md

@@ -0,0 +1,80 @@
+# SSH Commands
+
+SSH configuration and setup utilities.
+
+## Platform Support
+
+- ✅ **Linux** - Fully supported
+- ✅ **macOS** - Fully supported
+- ✅ **Windows** - Requires Git Bash or WSL
+  - Git Bash (included with Git for Windows) provides Unix-like `~/.ssh` directory
+  - Native Windows SSH uses `%USERPROFILE%\.ssh` instead
+
+## init-dir
+
+Initialize SSH directory with proper permissions.
+
+### Usage
+
+```bash
+hlpr ssh init-dir
+```
+
+### What it does
+
+Creates the `~/.ssh` directory and essential SSH configuration files with correct permissions:
+
+1. Creates `~/.ssh` directory (if it doesn't exist)
+2. Creates `~/.ssh/known_hosts` file
+3. Creates `~/.ssh/config` file
+4. Sets directory permissions to 700 (rwx------)
+5. Sets file permissions to 644 (rw-r--r--)
+
+### Permissions explained
+
+- `~/.ssh/` → 700 (only owner can read/write/execute)
+- `~/.ssh/known_hosts` → 644 (owner can write, others can read)
+- `~/.ssh/config` → 644 (owner can write, others can read)
+
+These permissions are required by SSH for security. If permissions are incorrect, SSH will refuse to use the files.
+
+### When to use
+
+- Setting up SSH on a new system
+- Fixing SSH permission issues
+- After accidentally deleting SSH configuration files
+
+### Example
+
+```bash
+$ hlpr ssh init-dir
+# Creates ~/.ssh/ with proper structure and permissions
+```
+
+### Verify
+
+```bash
+ls -la ~/.ssh/
+# Should show:
+# drwx------  ~/.ssh/
+# -rw-r--r--  ~/.ssh/config
+# -rw-r--r--  ~/.ssh/known_hosts
+```
+
+### Note
+
+This command will fail if `~/.ssh` already exists. If you need to fix permissions on an existing directory, you can:
+
+```bash
+chmod 700 ~/.ssh
+chmod 644 ~/.ssh/known_hosts
+chmod 644 ~/.ssh/config
+```
+
+### Next steps
+
+After initializing the SSH directory, you typically:
+
+1. Generate SSH keys: `ssh-keygen -t ed25519 -C "your_email@example.com"`
+2. Add SSH config entries to `~/.ssh/config`
+3. Add public key to remote servers or services (GitHub, GitLab, etc.)

package/bin/index.js

@@ -6,7 +6,6 @@ import { exec } from "node:child_process";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import * as readline from "node:readline";
-import * as os from "node:os";
 import { fileURLToPath } from "node:url";
 async function getVersion() {
   try {
@@ -20,13 +19,6 @@ async function getVersion() {
     return "0.0.0";
   }
 }
-function detectShell() {
-  const isWindows = os.platform() === "win32";
-  if (isWindows) {
-    return "powershell";
-  }
-  return "bash";
-}
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = path.dirname(__filename2);
 var scriptDir = path.join(__dirname2, "..", "src");
@@ -245,7 +237,7 @@ async function main() {
       }
     }
     if (!isTypeScriptCommand && restArgs.length > 0) {
-      const scriptName = restArgs.join("");
+      const scriptName = restArgs[0];
       let scriptPathCandidate = path.join(scriptDir, "commands", category, `${scriptName}.sh`);
       if (!fs.existsSync(scriptPathCandidate)) {
         scriptPathCandidate = path.join(__dirname2, "..", "bin", "commands", category, `${scriptName}.sh`);
@@ -273,8 +265,8 @@ async function main() {
       const finalCommand = `node "${scriptPath}" ${tsArgs.join(" ")}`;
       console.log(`Executing command: ${finalCommand}`);
       const success2 = await executeCommand(finalCommand, {});
-      const helpFlags = ["-h", "--help", "help", "/h", "/help", "/?"];
-      const isHelpInvocation = tsArgs.some((arg) => helpFlags.includes(arg));
+      const helpFlags2 = ["-h", "--help", "help", "/h", "/help", "/?"];
+      const isHelpInvocation = tsArgs.some((arg) => helpFlags2.includes(arg));
       if (!success2 && !forceFlag && !isHelpInvocation) {
         console.error("Command failed, stopping execution.");
         process.exit(1);
@@ -284,6 +276,7 @@ async function main() {
       return;
     }
     const scriptContent = await readFile(scriptPath, "utf-8");
+    const scriptArgs = restArgs.slice(1);
     const variableRegex = /{{([^}]+)}}/g;
     const variables = {};
     const uniqueVars = new Set;
@@ -291,9 +284,13 @@ async function main() {
     while ((match = variableRegex.exec(scriptContent)) !== null) {
       uniqueVars.add(match[1]);
     }
-    for (const varName of uniqueVars) {
-      const value = await prompt(`Enter ${varName}: `);
-      variables[varName] = value;
+    const helpFlags = ["-h", "--help", "help", "/h", "/help", "/?"];
+    const isHelpRequested = scriptArgs.some((arg) => helpFlags.includes(arg));
+    if (!isHelpRequested) {
+      for (const varName of uniqueVars) {
+        const value = await prompt(`Enter ${varName}: `);
+        variables[varName] = value;
+      }
     }
     let processedScript = scriptContent;
     for (const [key, value] of Object.entries(variables)) {
@@ -301,8 +298,8 @@ async function main() {
     }
     const tempScriptPath = path.join(path.dirname(scriptPath), `_temp_${path.basename(scriptPath)}`);
     fs.writeFileSync(tempScriptPath, processedScript);
-    const shell = detectShell();
-    const command = shell === "powershell" ? `powershell -File "${tempScriptPath}"` : `bash "${tempScriptPath}"`;
+    const argsStr = scriptArgs.map((arg) => `"${arg}"`).join(" ");
+    const command = `bash "${tempScriptPath}" ${argsStr}`;
     const success = await executeCommand(command, {});
     fs.unlinkSync(tempScriptPath);
     if (!success && !forceFlag) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/hlpr",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Windows and *Nix utility for typical programming activity",
   "author": "Vitalii Balabanov",
   "email": "tertiumnon@gmail.com",