@tertium/hlpr 0.5.8 → 0.6.1

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/kill-port/kill-port.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/commands/process/kill-port/kill-port.ts
+import { execSync, spawnSync } from "child_process";
+import { platform } from "os";
+function getProcessOnWindowsPort(port) {
+  try {
+    const output = execSync(`netstat -ano | findstr :${port}`, { encoding: "utf-8" });
+    const pids = [];
+    const lines = output.split(`
+`);
+    for (const line of lines) {
+      const match = line.match(/\s+(\d+)\s*$/);
+      if (match) {
+        const pid = parseInt(match[1], 10);
+        if (pid > 0 && !pids.includes(pid)) {
+          pids.push(pid);
+        }
+      }
+    }
+    return pids;
+  } catch (error) {
+    return [];
+  }
+}
+function getProcessOnLinuxPort(port) {
+  try {
+    const output = execSync(`lsof -i :${port} -n -P`, { encoding: "utf-8" });
+    const pids = [];
+    const lines = output.split(`
+`);
+    for (let i = 1;i < lines.length; i++) {
+      const parts = lines[i].trim().split(/\s+/);
+      if (parts.length > 1) {
+        const pid = parseInt(parts[1], 10);
+        if (!isNaN(pid) && !pids.includes(pid)) {
+          pids.push(pid);
+        }
+      }
+    }
+    return pids;
+  } catch {
+    try {
+      const output = execSync(`netstat -tulnp 2>/dev/null | grep :${port}`, { encoding: "utf-8" });
+      const pids = [];
+      const lines = output.split(`
+`);
+      for (const line of lines) {
+        const match = line.match(/(\d+)\//);
+        if (match) {
+          const pid = parseInt(match[1], 10);
+          if (!pids.includes(pid)) {
+            pids.push(pid);
+          }
+        }
+      }
+      return pids;
+    } catch {
+      return [];
+    }
+  }
+}
+function killProcessOnWindows(pid, force, verbose) {
+  try {
+    const args = force ? ["/PID", pid.toString(), "/F"] : ["/PID", pid.toString()];
+    const result = spawnSync("taskkill", args, { encoding: "utf-8" });
+    if (result.status === 0) {
+      if (verbose)
+        console.log(`\u2713 Killed process ${pid}`);
+      return true;
+    } else {
+      if (verbose)
+        console.error(`\u2717 Failed to kill process ${pid}: ${result.stderr}`);
+      return false;
+    }
+  } catch (error) {
+    if (verbose)
+      console.error(`\u2717 Error killing process ${pid}: ${error}`);
+    return false;
+  }
+}
+function killProcessOnLinux(pid, force, verbose) {
+  try {
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    const result = spawnSync("kill", [`-${signal}`, pid.toString()], { encoding: "utf-8" });
+    if (result.status === 0) {
+      if (verbose)
+        console.log(`\u2713 Killed process ${pid} with ${signal}`);
+      return true;
+    } else {
+      if (verbose)
+        console.error(`\u2717 Failed to kill process ${pid}: ${result.stderr}`);
+      return false;
+    }
+  } catch (error) {
+    if (verbose)
+      console.error(`\u2717 Error killing process ${pid}: ${error}`);
+    return false;
+  }
+}
+async function killPort(port, options = {}) {
+  const { force = false, verbose = false } = options;
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port number: ${port}. Port must be between 1 and 65535.`);
+  }
+  const os = platform();
+  let pids = [];
+  if (verbose)
+    console.log(`Searching for processes on port ${port} (${os})...`);
+  if (os === "win32") {
+    pids = getProcessOnWindowsPort(port);
+  } else {
+    pids = getProcessOnLinuxPort(port);
+  }
+  if (pids.length === 0) {
+    if (verbose)
+      console.log(`No processes found on port ${port}`);
+    return { killed: [], failed: [] };
+  }
+  if (verbose)
+    console.log(`Found ${pids.length} process(es) on port ${port}: ${pids.join(", ")}`);
+  const killed = [];
+  const failed = [];
+  for (const pid of pids) {
+    let success;
+    if (os === "win32") {
+      success = killProcessOnWindows(pid, force, verbose);
+    } else {
+      success = killProcessOnLinux(pid, force, verbose);
+    }
+    if (success) {
+      killed.push(pid);
+    } else {
+      failed.push(pid);
+    }
+  }
+  return { killed, failed };
+}
+if (import.meta.url.endsWith(process.argv[1]?.replace(/\\/g, "/"))) {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    console.log("Usage: kill-port <port> [options]");
+    console.log("Kill process(es) running on a specified port (Windows & Linux support)");
+    console.log();
+    console.log("Arguments:");
+    console.log("  port                  Port number (1-65535)");
+    console.log();
+    console.log("Options:");
+    console.log("  -f, --force           Force kill (SIGKILL on Linux, /F on Windows)");
+    console.log("  -v, --verbose         Show verbose output");
+    console.log("  -h, --help            Show this help message");
+    console.log();
+    console.log("Examples:");
+    console.log("  hlpr process kill-port 3000");
+    console.log("  hlpr process kill-port 8080 --force");
+    console.log("  hlpr process kill-port 5432 -v");
+    process.exit(0);
+  }
+  const port = parseInt(args[0], 10);
+  const force = args.includes("-f") || args.includes("--force");
+  const verbose = args.includes("-v") || args.includes("--verbose");
+  killPort(port, { force, verbose }).then((result) => {
+    if (result.killed.length > 0) {
+      console.log(`Successfully killed ${result.killed.length} process(es) on port ${port}`);
+    }
+    if (result.failed.length > 0) {
+      console.error(`Failed to kill ${result.failed.length} process(es): ${result.failed.join(", ")}`);
+      process.exit(1);
+    }
+    if (result.killed.length === 0 && result.failed.length === 0) {
+      console.log(`No processes found on port ${port}`);
+    }
+    process.exit(0);
+  }).catch((error) => {
+    console.error("Error:", error.message);
+    process.exit(1);
+  });
+}
+var kill_port_default = { killPort };
+export {
+  killPort,
+  kill_port_default as default
+};

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