@tertium/hlpr 0.5.8 → 0.6.1

package/README.md

@@ -45,126 +45,23 @@ hlpr -f ssh init dir
 
 ## Available Commands
 
-### TypeScript Commands
-
-#### file rename
-
-Recursively rename files and folders according to a specific case style.
-
-**Supported styles:**
-- `title_underscore` - Title_Case_With_Underscores
-- `snake` - snake_case_lowercase
-- `kebab` - kebab-case-lowercase
-- `camel` - camelCaseLowerFirst
-- `pascal` - PascalCaseUpperFirst
-- `upper` - UPPER_CASE_WITH_UNDERSCORES
-- `lower` - lower_case_with_underscores
-
-**Usage:**
-```bash
-# Dry run (preview changes without applying)
-hlpr file rename ./my-project kebab --dry
-hlpr file rename ./src snake -n
-
-# Apply changes
-hlpr file rename ./my-project kebab
-hlpr file rename ./docs pascal
-```
-
-**Features:**
-- ✅ Recursive directory traversal
-- ✅ Extension preservation
-- ✅ Leading dot file support (e.g., `.gitignore`)
-- ✅ Case-only rename handling (Windows compatibility)
-- ✅ Conflict resolution (adds `_N` suffix)
-- ✅ Dry-run mode (`--dry` or `-n`)
-
-**See:** [`src/commands/file/rename/README.md`](src/commands/file/rename/README.md) for full documentation.
-
----
-
-#### help
+See individual command documentation for detailed usage, options, and examples.
 
-Display help information about hlpr commands.
-
-**Usage:**
-```bash
-hlpr help
-```
+### TypeScript Commands
 
----
+- **[file rename](src/commands/file/rename/README.md)** - Recursively rename files/folders with various case styles
+- **[help](src/commands/help/README.md)** - Display help information about hlpr commands
+- **[process list-port](src/commands/process/list-port/README.md)** - List processes running on a port
+- **[process kill-port](src/commands/process/kill-port/README.md)** - Kill processes on a port
 
 ### Shell Script Commands
 
 Shell scripts support variable substitution using `{{variable}}` syntax.
 
-#### git
-
-Helpful git utilities for common development workflows.
-
-**Usage:**
-```bash
-hlpr git <command>
-```
-
-**Commands:**
-- `fodd` - Fetch and update develop branch from origin
-- `precommit` - Run build and stage binaries before commit
-- `switch-clean` - Safely switch to a branch and delete the previous one (local & remote)
-
-**See:** [`src/commands/git/README.md`](src/commands/git/README.md) for full documentation.
-
----
-
-#### hello
-
-Example/demo commands for testing the hlpr CLI tool.
-
-**Usage:**
-```bash
-hlpr hello world
-```
-
-Prompts for input and prints a personalized greeting with variable substitution.
-
-**See:** [`src/commands/hello/README.md`](src/commands/hello/README.md) for full documentation.
-
----
-
-#### nvm
-
-Node Version Manager utilities for managing Node.js versions.
-
-**Usage:**
-```bash
-hlpr nvm <command>
-```
-
-**Commands:**
-- `install` - Install Node Version Manager (nvm)
-- `lts` - Install and use Node.js LTS version
-
-**See:** [`src/commands/nvm/README.md`](src/commands/nvm/README.md) for full documentation.
-
----
-
-#### ssh
-
-SSH configuration and setup utilities.
-
-**Usage:**
-```bash
-hlpr ssh init-dir
-```
-
-Initializes SSH directory with proper permissions:
-- `~/.ssh/` directory with 700 permissions
-- `~/.ssh/known_hosts` with 644 permissions
-- `~/.ssh/config` with 644 permissions
-
-Portable across Unix/Linux/macOS and Git Bash on Windows.
-
-**See:** [`src/commands/ssh/README.md`](src/commands/ssh/README.md) for full documentation.
+- **[git](src/commands/git/README.md)** - Git utilities (fodd, precommit, switch-clean)
+- **[hello](src/commands/hello/README.md)** - Example greeting command with variable substitution
+- **[nvm](src/commands/nvm/README.md)** - Node Version Manager utilities
+- **[ssh](src/commands/ssh/README.md)** - SSH configuration and setup utilities
 
 ## How It Works
 
@@ -183,21 +80,40 @@ Portable across Unix/Linux/macOS and Git Bash on Windows.
 ## Directory Structure
 
 ```
-commands/
-├── file/
-│   └── rename/
-│       ├── rename.ts
-│       ├── rename.test.ts
+src/
+├── core/
+│   └── command/
+│       └── command.types.ts
+├── commands/
+│   ├── file/
+│   │   └── rename/
+│   │       ├── rename.ts
+│   │       ├── rename.test.ts
+│   │       └── README.md
+│   ├── git/
+│   │   ├── fodd.sh
+│   │   ├── precommit.sh
+│   │   ├── switch-clean.sh
+│   │   └── README.md
+│   ├── hello/
+│   │   ├── world.sh
+│   │   └── README.md
+│   ├── nvm/
+│   │   ├── install.sh
+│   │   ├── lts.sh
+│   │   └── README.md
+│   ├── process/
+│   │   ├── kill-port/
+│   │   │   ├── kill-port.ts
+│   │   │   └── README.md
+│   │   └── list-port/
+│   │       ├── list-port.ts
+│   │       └── README.md
+│   └── ssh/
+│       ├── init-dir.sh
 │       └── README.md
-├── git/
-│   └── fodd.sh
-├── hello/
-│   └── world.sh
-├── nvm/
-│   ├── install.sh
-│   └── lts.sh
-└── ssh/
-    └── initdir.sh
+├── index.ts
+└── commands.ts
 ```
 
 ## Adding Your Own Scripts
@@ -246,6 +162,113 @@ The utility maps command arguments to script files:
 
 - `hlpr file rename <args>` → runs `commands/file/rename/rename.ts`
 
+## How Shell Scripts (.sh) Work
+
+Shell scripts are bash scripts stored in `src/commands/<category>/` directories. They support interactive variable substitution and are cross-platform compatible.
+
+### Variable Substitution
+
+Shell scripts can use `{{variable}}` placeholders for user input:
+
+```bash
+#!/bin/bash
+# Example: src/commands/greet/hello.sh
+echo "Hello {{name}}, welcome to {{place}}"
+```
+
+When you run `hlpr greet hello`, the utility:
+1. Reads the script
+2. Finds all `{{variable}}` placeholders
+3. Prompts you to enter values for each variable
+4. Executes the script with variables replaced
+
+**Example interaction:**
+```
+$ hlpr greet hello
+Enter value for name: Alice
+Enter value for place: Wonderland
+Hello Alice, welcome to Wonderland
+```
+
+### Script Execution
+
+- Each line of the script is executed sequentially
+- If any line fails and `-f` flag is not set, execution stops
+- Scripts have access to standard bash features (pipes, redirects, etc.)
+
+### Windows Compatibility
+
+`.sh` scripts run on Windows through **PowerShell** and the modern cross-platform command stack.
+
+**How it works:**
+
+1. User runs: `hlpr git fodd`
+2. hlpr detects the platform is Windows
+3. hlpr invokes **PowerShell** to execute the `.sh` script
+4. PowerShell (v7+) and installed tools provide Unix-like command support
+5. Commands like `grep`, `sed`, `ls`, etc. work through various implementations
+
+**Why this works:**
+
+Modern Windows systems have multiple sources for Unix-like commands:
+
+- **PowerShell 7+** - Cross-platform, provides built-in Unix-like commands and aliases (ls, grep, select-string, etc.)
+- **Git** - Installs Unix utilities as part of its toolchain
+- **Node.js** - Provides command-line tools that work cross-platform
+- **Package managers** - scoop, chocolatey, and winget provide Unix tools
+- **WSL 2** - Windows Subsystem for Linux provides full Linux compatibility
+
+Scripts work because:
+- Modern tools use consistent command-line interfaces across platforms
+- PowerShell Core has native cross-platform support
+- Common utilities are available through multiple sources in system PATH
+
+**Example:**
+
+```bash
+#!/bin/bash
+# This script works on Windows, Linux, and macOS
+echo "Running on: $(uname -s || echo 'Windows PowerShell')"
+if [ -d "./src" ]; then
+  echo "Found src directory"
+  ls src | head -5
+fi
+```
+
+**Requirements:**
+
+- **Modern PowerShell** (v7+) is recommended for full compatibility
+- **Windows 10+** with default PowerShell Core support
+- **Git** installed (provides additional Unix utilities)
+- **Node.js** for runtime support
+
+No special configuration needed - hlpr automatically detects and uses PowerShell on Windows.
+
+### Creating Shell Scripts
+
+1. Create directory: `src/commands/<category>/`
+2. Add `.sh` file: `<command>.sh`
+3. Add shebang: `#!/bin/bash`
+4. Use `{{variable}}` for user input
+5. Build with `bun run build` (copies `.sh` files to `bin/commands/`)
+
+Example:
+
+```bash
+#!/bin/bash
+# src/commands/greet/hello.sh
+NAME={{name}}
+echo "Hello $NAME!"
+echo "Today is $(date '+%A')"
+```
+
+### Building and Distribution
+
+Shell scripts are:
+- **Copied** (not compiled) during build to `bin/commands/`
+- **Distributed** as part of the published package
+- **Platform-compatible** across Linux, macOS, and Windows (with Git Bash)
+
 ## Error Handling
 
 By default, the utility stops execution if any command fails. Use the `-f` flag to continue execution despite failures:
@@ -263,10 +286,14 @@ hlpr -f ssh init dir
 ```bash
 # Clone the repository
 git clone https://github.com/tertiumnon/hlpr.git
+cd hlpr
 
 # Install dependencies
 npm install
 
+# Setup git hooks (runs tests before commit)
+npm run setup:hooks
+
 # Build the project
 bun run build
 
@@ -274,6 +301,20 @@ bun run build
 npm link
 ```
 
+### Git Hooks
+
+This project uses native git hooks (`.githooks/pre-commit`) to run tests before each commit. After cloning or pulling, ensure hooks are configured:
+
+```bash
+npm run setup:hooks
+```
+
+The pre-commit hook:
+- Runs unit and integration tests
+- Runs end-to-end tests
+- Aborts commit if tests fail
+- Can be skipped with `SKIP_E2E=1 git commit` (not recommended)
+
 ## License
 
 MIT

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/file/rename/rename.js

@@ -1,3 +1,4 @@
+// @bun
 // src/commands/file/rename/rename.ts
 import fs from "fs/promises";
 import path from "path";
@@ -21,7 +22,7 @@ function transformBasename(basename, style) {
     return basename;
   switch (style) {
     case "title_underscore":
-      return leadingDot + words.map(cap).join("_") + ext;
+      return leadingDot + titleCase(words).join("_") + ext;
     case "snake":
       return leadingDot + words.map((w) => w.toLowerCase()).join("_") + ext;
     case "kebab":
@@ -31,7 +32,7 @@ function transformBasename(basename, style) {
     case "pascal":
       return leadingDot + words.map(cap).join("") + ext;
     case "pascal_underscore":
-      return leadingDot + words.map(cap).join("_") + ext;
+      return leadingDot + titleCase(words).join("_") + ext;
     case "upper":
       return leadingDot + words.join("_").toUpperCase() + ext;
     case "lower":
@@ -40,11 +41,48 @@ function transformBasename(basename, style) {
       return leadingDot + core + ext;
   }
 }
+function isAllCaps(s) {
+  return s.length > 0 && s === s.toUpperCase() && s !== s.toLowerCase();
+}
 function cap(s) {
   if (!s)
     return s;
   return s[0].toUpperCase() + s.slice(1).toLowerCase();
 }
+function titleCase(words) {
+  const smallWords = new Set([
+    "a",
+    "an",
+    "and",
+    "as",
+    "at",
+    "but",
+    "by",
+    "for",
+    "from",
+    "in",
+    "into",
+    "nor",
+    "of",
+    "on",
+    "or",
+    "the",
+    "to",
+    "with"
+  ]);
+  return words.map((word, index) => {
+    if (isAllCaps(word)) {
+      return word;
+    }
+    if (index === 0) {
+      return cap(word);
+    }
+    if (smallWords.has(word.toLowerCase())) {
+      return word.toLowerCase();
+    }
+    return cap(word);
+  });
+}
 async function exists(p) {
   try {
     await fs.access(p);
@@ -229,7 +267,7 @@ if (import.meta.url.endsWith(process.argv[1]?.replace(/\\/g, "/"))) {
       console.log(`Renamed ${performed.length} items:`);
     }
     performed.forEach(({ from, to }) => {
-      console.log(`  ${from} → ${to}`);
+      console.log(`  ${from} \u2192 ${to}`);
     });
   }).catch((err) => {
     console.error("Error:", err);