@tertium/hlpr 0.6.3 → 0.7.0

package/README.md

@@ -38,6 +38,7 @@ hlpr ssh init dir
 
 # TypeScript commands (nested structure)
 hlpr file rename <directory> <style> [--dry|-n]
+hlpr file mv <oldPath> <newPath> [--dry|-n]
 
 # Continue execution even if commands fail
 hlpr -f ssh init dir
@@ -50,6 +51,7 @@ See individual command documentation for detailed usage, options, and examples.
 ### TypeScript Commands
 
 - **[file rename](src/commands/file/rename/README.md)** - Recursively rename files/folders with various case styles
+- **[file mv](src/commands/file/mv/README.md)** - Rename/move a single file and update all references to it (markdown links, wikilinks, imports)
 - **[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

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

@@ -0,0 +1,96 @@
+# File Mv Command
+
+Rename or move a single file and automatically update every reference to it — markdown links,
+wikilinks, and quoted import/require/href/src paths — in every text file under a directory, recursively.
+
+No extension filtering is applied when scanning: every text file under the root is checked, and
+binary files are skipped automatically.
+
+## Usage
+
+```bash
+hlpr file mv <oldPath> <newPath> [--root <dir>] [--dry|-n] [--force] [--no-update-content]
+```
+
+### Arguments
+
+- `<oldPath>` - Path to the existing file
+- `<newPath>` - New path or filename. If it has no directory separators, the file is renamed
+  in place (kept in the same directory as `<oldPath>`); otherwise it's treated as a full path
+  and the file is moved there (missing directories are created).
+- `--root <dir>` - Directory to scan for references (default: current directory)
+- `--dry` or `-n` - Preview changes without applying them
+- `--force` - Overwrite the destination file if it already exists
+- `--no-update-content` - Skip updating references in other files (only rename/move the file)
+
+## Examples
+
+```bash
+# Rename a markdown file in place and fix every link to it
+hlpr file mv docs/old-name.md new-name.md
+
+# Preview what would change first
+hlpr file mv docs/old-name.md new-name.md --dry
+
+# Move a file into another folder
+hlpr file mv docs/old-name.md docs/archive/old-name.md
+
+# Only scan a specific subtree for references
+hlpr file mv docs/old-name.md new-name.md --root docs
+
+# Overwrite an existing destination file
+hlpr file mv docs/old-name.md docs/existing.md --force
+```
+
+## What Gets Updated
+
+For every text file under `--root` (default: current directory), the command rewrites:
+
+- **Markdown links & images**: `[text](./old-name.md)`, `![alt](../old-name.md)`, including
+  `<path with spaces>` wrapping, `#heading` fragments, and `"title"` suffixes.
+- **Wikilinks**: `[[old-name]]`, `[[old-name|Alias]]`, `[[old-name#Section]]`. Bare wikilinks
+  (no path, Obsidian-style) are matched by basename across the whole scanned root — but only
+  when that basename is unique. If another file shares the same basename anywhere under the
+  root, bare wikilinks are left untouched to avoid an ambiguous rewrite (the command reports
+  this in its output).
+- **Quoted paths**: `'./old-name'`, `"../old-name.md"`, `` `./old-name` `` — covers JS/TS
+  imports and requires, and HTML `href`/`src` attributes.
+
+Each reference is resolved relative to the *referencing file's own directory* (or to `--root`
+for root-relative/leading-`/` links) before being matched, so files in different folders each
+get the correct relative path to the new location — not just a blind text substitution.
+
+Links to unrelated files, and links using absolute URLs (`http://`, `mailto:`, etc.), are never
+touched.
+
+## Safety
+
+- Errors out if the destination already exists, unless `--force` is passed.
+- Handles case-only renames correctly on case-insensitive filesystems (Windows/macOS).
+- `--dry` reports exactly what would be renamed and which files would be updated (and how many
+  references in each), without touching disk.
+- Skips `.git` and `node_modules` when scanning for references.
+
+## TypeScript API
+
+```typescript
+import { renameFile } from './commands/file/mv/mv.js'
+
+const result = await renameFile('docs/old-name.md', 'new-name.md', {
+  root: 'docs',
+  dryRun: false,
+  force: false,
+  updateContent: true,
+})
+
+// result.from / result.to           — resolved absolute paths
+// result.updatedFiles                — [{ file, count }, ...]
+// result.bareBasenameAmbiguous       — true if bare wikilinks were skipped due to a name clash
+```
+
+## See Also
+
+- [Main hlpr README](../../../../README.md)
+- [file rename](../rename/README.md) - bulk case-style renaming for whole directory trees
+- [TypeScript Implementation](./mv.ts)
+- [Tests](./mv.test.ts)

package/bin/commands/file/mv/mv.js

@@ -0,0 +1,330 @@
+#!/usr/bin/env bun
+// @bun
+
+// src/commands/file/mv/mv.ts
+import fs from "fs/promises";
+import path from "path";
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function pathsEqual(a, b) {
+  const ra = path.resolve(a);
+  const rb = path.resolve(b);
+  return process.platform === "win32" ? ra.toLowerCase() === rb.toLowerCase() : ra === rb;
+}
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+async function isTextFile(filePath) {
+  try {
+    const fd = await fs.open(filePath, "r");
+    const buffer = Buffer.alloc(512);
+    const { bytesRead } = await fd.read(buffer, 0, 512, 0);
+    await fd.close();
+    if (bytesRead === 0)
+      return true;
+    for (let i = 0;i < bytesRead; i++) {
+      if (buffer[i] === 0)
+        return false;
+    }
+    let printableCount = 0;
+    for (let i = 0;i < bytesRead; i++) {
+      const byte = buffer[i];
+      if (byte >= 32 && byte <= 126 || byte === 9 || byte === 10 || byte === 13) {
+        printableCount++;
+      }
+    }
+    return printableCount / bytesRead > 0.85;
+  } catch {
+    return false;
+  }
+}
+var DEFAULT_IGNORED_DIRS = new Set([".git", "node_modules"]);
+async function collectFiles(dir, out = []) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    if (e.isDirectory() && DEFAULT_IGNORED_DIRS.has(e.name))
+      continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      await collectFiles(full, out);
+    } else if (e.isFile()) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+async function performRename(oldAbs, newAbs, force) {
+  await fs.mkdir(path.dirname(newAbs), { recursive: true });
+  const destExists = await exists(newAbs);
+  const caseOnlyChange = destExists && oldAbs !== newAbs && oldAbs.toLowerCase() === newAbs.toLowerCase();
+  if (destExists && !caseOnlyChange) {
+    if (!force) {
+      throw new Error(`Destination already exists: ${newAbs} (use --force to overwrite)`);
+    }
+    await fs.rm(newAbs);
+  }
+  if (caseOnlyChange) {
+    const tmp = newAbs + "__tmp_renaming__";
+    await fs.rename(oldAbs, tmp);
+    try {
+      await fs.rename(tmp, newAbs);
+    } catch (err) {
+      await fs.rename(tmp, oldAbs).catch(() => {});
+      throw err;
+    }
+  } else {
+    await fs.rename(oldAbs, newAbs);
+  }
+}
+function isExternalLink(target) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("//");
+}
+function splitFragment(target) {
+  const idx = target.indexOf("#");
+  if (idx === -1)
+    return { path: target, fragment: "" };
+  return { path: target.slice(0, idx), fragment: target.slice(idx) };
+}
+function safeDecodeURIComponent(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+function encodeLikeOriginal(newPathStr, original) {
+  if (/%20/.test(original)) {
+    return newPathStr.replace(/ /g, "%20");
+  }
+  return newPathStr;
+}
+function resolveTargetMatch(targetPath, fileDir, root, oldAbs, oldExt) {
+  const hadExt = !!path.extname(targetPath);
+  const withDefaultExt = (p) => hadExt ? [p] : [p, p + oldExt];
+  if (targetPath.startsWith("/")) {
+    const resolved = path.resolve(root, "." + targetPath);
+    return withDefaultExt(resolved).some((c) => pathsEqual(c, oldAbs)) ? "root-relative" : null;
+  }
+  const fileResolved = path.resolve(fileDir, targetPath);
+  if (withDefaultExt(fileResolved).some((c) => pathsEqual(c, oldAbs)))
+    return "file-relative";
+  const rootResolved = path.resolve(root, targetPath);
+  if (withDefaultExt(rootResolved).some((c) => pathsEqual(c, oldAbs)))
+    return "root-relative";
+  return null;
+}
+function tryRewriteTarget(rawTarget, fileDir, root, oldAbs, newAbs, allowBareBasename) {
+  if (!rawTarget || isExternalLink(rawTarget))
+    return null;
+  const { path: targetPath, fragment } = splitFragment(rawTarget);
+  if (!targetPath)
+    return null;
+  const decoded = safeDecodeURIComponent(targetPath);
+  const oldExt = path.extname(oldAbs);
+  const newExt = path.extname(newAbs);
+  const hadExt = !!path.extname(decoded);
+  const hasSlash = decoded.includes("/") || decoded.includes("\\");
+  let matchKind = null;
+  if (allowBareBasename && !hasSlash) {
+    const compareBase = hadExt ? decoded : decoded + oldExt;
+    if (pathsEqual(path.basename(compareBase), path.basename(oldAbs))) {
+      matchKind = "bare-basename";
+    }
+  }
+  if (!matchKind) {
+    matchKind = resolveTargetMatch(decoded, fileDir, root, oldAbs, oldExt);
+  }
+  if (!matchKind)
+    return null;
+  let newTargetPath;
+  if (matchKind === "bare-basename") {
+    const newBase = path.basename(newAbs, newExt);
+    newTargetPath = hadExt ? newBase + newExt : newBase;
+  } else {
+    const base = matchKind === "root-relative" ? root : fileDir;
+    let rel = toPosix(path.relative(base, newAbs));
+    if (!hadExt && newExt && rel.endsWith(newExt)) {
+      rel = rel.slice(0, -newExt.length);
+    }
+    const wasRootAbsolute = decoded.startsWith("/");
+    const wasExplicitRelative = decoded.startsWith("./") || decoded.startsWith("../");
+    if (wasRootAbsolute) {
+      newTargetPath = "/" + rel;
+    } else if (wasExplicitRelative || rel.startsWith("..")) {
+      newTargetPath = rel.startsWith(".") ? rel : "./" + rel;
+    } else {
+      newTargetPath = rel;
+    }
+  }
+  return encodeLikeOriginal(newTargetPath, targetPath) + fragment;
+}
+function parseMdTarget(raw) {
+  const s = raw.trim();
+  if (s.startsWith("<")) {
+    const end = s.indexOf(">");
+    if (end !== -1) {
+      return { link: s.slice(1, end), suffix: s.slice(end + 1), wrapped: true };
+    }
+  }
+  const titleIdx = s.search(/\s+["']/);
+  if (titleIdx !== -1) {
+    return { link: s.slice(0, titleIdx), suffix: s.slice(titleIdx), wrapped: false };
+  }
+  return { link: s, suffix: "", wrapped: false };
+}
+function parseWikiTarget(raw) {
+  const idx = raw.search(/[#|]/);
+  if (idx === -1)
+    return { link: raw, rest: "" };
+  return { link: raw.slice(0, idx), rest: raw.slice(idx) };
+}
+function rewriteContent(content, fileDir, root, oldAbs, newAbs, allowBareBasename) {
+  let count = 0;
+  let updated = content;
+  updated = updated.replace(/(!?\[[^\]]*\])\(([^)]+)\)/g, (full, textPart, rawTarget) => {
+    const { link, suffix, wrapped } = parseMdTarget(rawTarget);
+    const newLink = tryRewriteTarget(link, fileDir, root, oldAbs, newAbs, false);
+    if (newLink === null)
+      return full;
+    count++;
+    const rebuilt = wrapped ? `<${newLink}>` : newLink;
+    return `${textPart}(${rebuilt}${suffix})`;
+  });
+  updated = updated.replace(/\[\[([^\]]+)\]\]/g, (full, inner) => {
+    const { link, rest } = parseWikiTarget(inner);
+    const newLink = tryRewriteTarget(link, fileDir, root, oldAbs, newAbs, allowBareBasename);
+    if (newLink === null)
+      return full;
+    count++;
+    return `[[${newLink}${rest}]]`;
+  });
+  updated = updated.replace(/(['"`])([^'"`]*\/[^'"`]*)\1/g, (full, quote, rawTarget) => {
+    const newLink = tryRewriteTarget(rawTarget, fileDir, root, oldAbs, newAbs, false);
+    if (newLink === null)
+      return full;
+    count++;
+    return `${quote}${newLink}${quote}`;
+  });
+  return { content: updated, count };
+}
+async function renameFile(oldPathArg, newPathArg, options = {}) {
+  const oldAbs = path.resolve(oldPathArg);
+  const hasDirSeparator = newPathArg.includes("/") || newPathArg.includes("\\");
+  const newAbs = hasDirSeparator ? path.resolve(newPathArg) : path.join(path.dirname(oldAbs), newPathArg);
+  const root = path.resolve(options.root ?? process.cwd());
+  const updateContentEnabled = options.updateContent ?? true;
+  const dryRun = options.dryRun ?? false;
+  const force = options.force ?? false;
+  if (!await exists(oldAbs)) {
+    throw new Error(`Source file does not exist: ${oldAbs}`);
+  }
+  const oldStat = await fs.stat(oldAbs);
+  if (!oldStat.isFile()) {
+    throw new Error(`Source is not a file: ${oldAbs}`);
+  }
+  if (pathsEqual(oldAbs, newAbs) && oldAbs === newAbs) {
+    throw new Error("Source and destination are the same path");
+  }
+  const result = { from: oldAbs, to: newAbs, updatedFiles: [], bareBasenameAmbiguous: false };
+  const allFiles = updateContentEnabled ? await collectFiles(root) : [];
+  const oldBasenameLower = path.basename(oldAbs).toLowerCase();
+  const sameBasenameElsewhere = allFiles.some((f) => !pathsEqual(f, oldAbs) && path.basename(f).toLowerCase() === oldBasenameLower);
+  const allowBareBasename = !sameBasenameElsewhere;
+  result.bareBasenameAmbiguous = sameBasenameElsewhere;
+  if (!dryRun) {
+    await performRename(oldAbs, newAbs, force);
+  }
+  if (updateContentEnabled) {
+    for (const file of allFiles) {
+      if (pathsEqual(file, oldAbs) || pathsEqual(file, newAbs))
+        continue;
+      if (!await isTextFile(file))
+        continue;
+      const original = await fs.readFile(file, "utf-8");
+      const { content: updated, count } = rewriteContent(original, path.dirname(file), root, oldAbs, newAbs, allowBareBasename);
+      if (count > 0) {
+        result.updatedFiles.push({ file, count });
+        if (!dryRun) {
+          await fs.writeFile(file, updated, "utf-8");
+        }
+      }
+    }
+  }
+  return result;
+}
+if (import.meta.url.endsWith(process.argv[1]?.replace(/\\/g, "/"))) {
+  const rawArgs = process.argv.slice(2);
+  if (rawArgs.includes("--help") || rawArgs.includes("-h") || rawArgs.includes("/help") || rawArgs.includes("/h") || rawArgs.includes("/?")) {
+    console.log("Usage: mv <oldPath> <newPath> [--root <dir>] [--dry|-n] [--force] [--no-update-content]");
+    console.log("Renames/moves a single file and updates references to it (markdown links, wikilinks,");
+    console.log("imports, href/src) in every text file under <dir> (default: current directory), recursively.");
+    console.log("Options:");
+    console.log("  --root <dir>           Directory to scan for references (default: current directory)");
+    console.log("  --dry, -n              Preview changes without applying them");
+    console.log("  --force                Overwrite destination file if it already exists");
+    console.log("  --no-update-content    Skip updating references in other files");
+    process.exit(0);
+  }
+  const positional = [];
+  let root;
+  let dryRun = false;
+  let force = false;
+  let updateContent = true;
+  for (let i = 0;i < rawArgs.length; i++) {
+    const a = rawArgs[i];
+    if (a === "--dry" || a === "-n")
+      dryRun = true;
+    else if (a === "--force")
+      force = true;
+    else if (a === "--no-update-content")
+      updateContent = false;
+    else if (a === "--root")
+      root = rawArgs[++i];
+    else
+      positional.push(a);
+  }
+  const [oldPathArg, newPathArg] = positional;
+  if (!oldPathArg || !newPathArg) {
+    console.error("Usage: mv <oldPath> <newPath> [--root <dir>] [--dry|-n] [--force] [--no-update-content]");
+    process.exit(1);
+  }
+  renameFile(oldPathArg, newPathArg, { root, dryRun, force, updateContent }).then((result) => {
+    if (dryRun) {
+      console.log(`Dry run - would rename:
+  ${result.from} \u2192 ${result.to}`);
+    } else {
+      console.log(`Renamed:
+  ${result.from} \u2192 ${result.to}`);
+    }
+    if (result.updatedFiles.length > 0) {
+      console.log(`
+${dryRun ? "Would update" : "Updated"} ${result.updatedFiles.length} file(s):`);
+      result.updatedFiles.forEach(({ file, count }) => {
+        console.log(`  ${file} (${count} reference${count === 1 ? "" : "s"})`);
+      });
+    } else {
+      console.log(`
+No references found to update.`);
+    }
+    if (result.bareBasenameAmbiguous) {
+      console.log(`
+Note: another file also named "${path.basename(result.from)}" exists under the scanned root, ` + "so bare wikilinks (e.g. [[name]]) were not auto-matched to avoid an ambiguous rewrite.");
+    }
+  }).catch((err) => {
+    console.error("Error:", err.message ?? err);
+    process.exit(1);
+  });
+}
+var mv_default = {
+  renameFile
+};
+export {
+  mv_default as default,
+  renameFile
+};

package/bin/commands/file/mv/mv.types.js

@@ -0,0 +1 @@
+// @bun

package/bin/commands/file/rename/rename.js

@@ -279,7 +279,7 @@ var rename_default = {
   renameRecursive
 };
 export {
-  transformBasename,
+  rename_default as default,
   renameRecursive,
-  rename_default as default
+  transformBasename
 };

package/bin/commands/file/rename/rename.types.js

@@ -0,0 +1 @@
+// @bun

package/bin/commands/help/help.types.js

@@ -0,0 +1 @@
+// @bun

package/bin/commands/process/kill-port/kill-port.js

@@ -179,6 +179,6 @@ if (import.meta.url.endsWith(process.argv[1]?.replace(/\\/g, "/"))) {
 }
 var kill_port_default = { killPort };
 export {
-  killPort,
-  kill_port_default as default
+  kill_port_default as default,
+  killPort
 };

package/bin/commands/process/list-port/list-port.js

@@ -159,6 +159,6 @@ if (import.meta.url.endsWith(process.argv[1]?.replace(/\\/g, "/"))) {
 }
 var list_port_default = { listPort };
 export {
-  listPort,
-  list_port_default as default
+  list_port_default as default,
+  listPort
 };

package/bin/commands/process/list-port/list-port.types.js

@@ -0,0 +1 @@
+// @bun

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tertium/hlpr",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Windows and *Nix utility for typical programming activity",
   "author": "Vitalii Balabanov",
   "email": "tertiumnon@gmail.com",
@@ -22,7 +22,8 @@
     "@tertium/js": "^1.4.7"
   },
   "devDependencies": {
-    "@types/node": "^22.13.10",
+    "@types/bun": "^1.4.1",
+    "@types/node": "^26.4.1",
     "typescript": "^5.8.3"
   },
   "bin": {