shellscripts 0.23.1__py3-none-any.whl

shell_scripts/commands/bin_links.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+
+from shell_scripts.utils import print_error
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Create or update command symlinks in $HOME/bin."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} bin-links [options] ({version})")
+    print()
+    print("bin-links options:")
+    print(
+        "  <directory>    - Source directory containing files to link (default: current dir)."
+    )
+    print("  --dest <dir>   - Destination directory for symlinks (default: $HOME/bin).")
+    print("  --help         - Show this help message.")
+
+
+def run(args):
+    src_dir = Path.cwd()
+    dest_dir = Path.home() / "bin"
+
+    i = 0
+    while i < len(args):
+        if args[i] == "--dest":
+            if i + 1 >= len(args):
+                print_error("--dest requires a directory path.")
+                return 1
+            dest_dir = Path(args[i + 1])
+            i += 2
+        elif not args[i].startswith("-"):
+            src_dir = Path(args[i])
+            i += 1
+        else:
+            print_error(f"Unknown option: {args[i]}")
+            return 1
+
+    if not src_dir.is_dir():
+        print_error(f"Source directory not found: {src_dir}")
+        return 1
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    for file_path in sorted(src_dir.iterdir()):
+        if file_path.is_dir():
+            continue
+
+        filename = file_path.name
+        abs_src = file_path.resolve()
+        link_name = filename.removesuffix(".sh")
+        target_link = dest_dir / link_name
+
+        print(f"Examining: {filename}...")
+
+        if target_link.exists() or target_link.is_symlink():
+            if target_link.is_symlink():
+                current_target = target_link.resolve()
+                if current_target == abs_src:
+                    print(f"  [OK] Link already points correctly to {filename}.")
+                else:
+                    print("  [UPDATE] Link points elsewhere. Updating...")
+                    target_link.unlink()
+                    target_link.symlink_to(abs_src)
+            else:
+                print(
+                    f"  [ERROR] '{target_link}' is a regular file. "
+                    f"Skipping to avoid data loss.",
+                    file=sys.stderr,
+                )
+        else:
+            print("  [NEW] Creating symlink...")
+            target_link.symlink_to(abs_src)
+
+    print("--- Operation completed ---")
+    return 0

shell_scripts/commands/claude.py

@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+"""@brief Claude CLI launcher in project context.
+
+@details Ensures project-root prerequisite and executable availability before
+blocking subprocess invocation of user-local Claude binary.
+@satisfies REQ-017, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+from pathlib import Path
+
+from shell_scripts.utils import require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch Claude CLI with skip-permissions in the project context."
+
+
+def print_help(version):
+    """@brief Print command-specific help for `claude`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} claude [args...] ({version})")
+    print()
+    print("claude options:")
+    print("  All arguments are passed through to the Claude CLI.")
+    print("  --help  - Show this help message.")
+
+
+def run(args):
+    """@brief Launch Claude CLI after external executable validation.
+
+    @details Resolves project root, resolves user-local Claude executable path,
+    validates executable availability, then executes command via subprocess.
+    @param args {list[str]} Additional CLI args forwarded to Claude.
+    @return {int} Child process return code.
+    @satisfies REQ-017, REQ-055, REQ-056, REQ-064
+    """
+
+    require_project_root()
+    claude_bin = Path.home() / ".claude" / "bin" / "claude"
+    cmd = [str(claude_bin), "--dangerously-skip-permissions"] + args
+    cmd[0] = require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/clean.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+import os
+import shutil
+from pathlib import Path
+
+from shell_scripts.utils import require_project_root, print_error
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Find and delete cache directories under the project root."
+
+CACHE_DIRS = [
+    "__pycache__",
+    ".pytest_cache",
+    ".mypy_cache",
+    ".cache",
+    ".npm",
+    ".parcel-cache",
+    ".eslintcache",
+    ".sass-cache",
+    ".terragrunt-cache",
+    "htmlcov",
+]
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} clean [options] ({version})")
+    print()
+    print("clean options:")
+    print("  <directory>  - Target directory to search (default: git project root).")
+    print("  --yes        - Skip confirmation prompt and delete immediately.")
+    print("  --help       - Show this help message.")
+
+
+def run(args):
+    project_root = require_project_root()
+    target_dir = project_root
+    auto_confirm = False
+
+    for arg in args:
+        if arg == "--yes":
+            auto_confirm = True
+        elif not arg.startswith("-"):
+            target_dir = Path(arg)
+        else:
+            print_error(f"Unknown option: {arg}")
+            return 1
+
+    os.chdir(project_root)
+
+    print(f"--- Searching for cache directories in: {target_dir} ---")
+    print("Please wait, scanning...")
+
+    found = []
+    for dir_name in CACHE_DIRS:
+        for root, dirs, _ in os.walk(target_dir):
+            if dir_name in dirs:
+                found.append(os.path.join(root, dir_name))
+
+    if not found:
+        print("No cache directories found.")
+        return 0
+
+    print()
+    print("Found the following directories:")
+    print("---------------------------------")
+    for path in found:
+        print(f" -> {path}")
+    print("---------------------------------")
+    print(f"Total directories found: {len(found)}")
+    print()
+
+    if auto_confirm:
+        confirm = "y"
+    else:
+        try:
+            confirm = input(
+                "WARNING: Are you sure you want to permanently DELETE "
+                "these directories? (y/N): "
+            )
+        except (EOFError, KeyboardInterrupt):
+            print()
+            confirm = "n"
+
+    if confirm.lower() == "y":
+        print()
+        print("Deleting...")
+        count = 0
+        for path in found:
+            shutil.rmtree(path, ignore_errors=True)
+            count += 1
+            print(f"Deleted: {path}")
+        print()
+        print(f"Cleanup complete! {count} directories removed.")
+    else:
+        print()
+        print("Operation aborted. No files were touched.")
+
+    return 0

shell_scripts/commands/codex.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""@brief Codex CLI launcher with project-context auth file synchronization.
+
+@details Ensures project-local Codex context is prepared before command
+execution. The launcher copies auth state from `~/.codex/auth.json` into
+`<project>/.codex/auth.json` before CLI launch, sets
+`CODEX_HOME=<project>/.codex`, executes `codex --yolo`, then copies auth state
+back from project path to home path before returning, emitting one
+informational output line for each copy direction.
+@satisfies REQ-014, REQ-043, REQ-044, REQ-064
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from shell_scripts.utils import print_info, require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch OpenAI Codex CLI in the project context."
+
+
+def print_help(version: str) -> None:
+    """@brief Print command-specific help for `codex`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+    print(f"Usage: {PROGRAM} codex [args...] ({version})")
+    print()
+    print("codex options:")
+    print("  All arguments are passed through to the Codex CLI.")
+    print("  --help  - Show this help message.")
+
+
+def _copy_auth_file(
+    source_path: Path,
+    destination_path: Path,
+    direction_label: str,
+) -> None:
+    """@brief Copy Codex auth file while replacing destination file or symlink.
+
+    @details Ensures destination parent directory exists, removes an existing
+    destination entry when it is a file or symbolic link, then copies source
+    bytes to destination preserving metadata with `shutil.copy2`, then emits
+    one informational output line for copy evidence. Time complexity O(n) where
+    n is auth file size.
+    @param source_path {Path} Existing auth file source path.
+    @param destination_path {Path} Auth file destination path to overwrite.
+    @param direction_label {str} Copy direction descriptor shown in info output.
+    @return {None} Applies destination filesystem mutation.
+    @throws {OSError} If source read, destination unlink, or copy operation fails.
+    @satisfies REQ-043, REQ-044
+    """
+    destination_path.parent.mkdir(parents=True, exist_ok=True)
+    if destination_path.exists() or destination_path.is_symlink():
+        destination_path.unlink()
+    shutil.copy2(source_path, destination_path)
+    print_info(
+        f"Copied auth.json ({direction_label}): {source_path} -> {destination_path}"
+    )
+
+
+def run(args: list[str]) -> int:
+    """@brief Launch Codex CLI with project-scoped environment preparation.
+
+    @details Resolves project root, copies auth from home into project auth
+    file, emits copy evidence output, sets `CODEX_HOME=<project-root>/.codex`,
+    executes `codex --yolo` plus pass-through args through blocking subprocess
+    run, then copies project auth back to home path in a `finally` block with
+    reverse-direction copy evidence output.
+    @param args {list[str]} Additional CLI args forwarded to Codex.
+    @return {int} Child process return code.
+    @throws {OSError} Propagated for auth-file copy or process-launch failures.
+    @satisfies REQ-014, REQ-043, REQ-044, REQ-064
+    """
+    project_root = require_project_root()
+    project_auth_path = project_root / ".codex" / "auth.json"
+    home_auth_path = Path.home() / ".codex" / "auth.json"
+    _copy_auth_file(
+        home_auth_path,
+        project_auth_path,
+        "global config -> project config",
+    )
+    codex_home = str(project_root / ".codex")
+    os.environ["CODEX_HOME"] = codex_home
+    cmd = ["codex", "--yolo"] + args
+    cmd[0] = require_commands(cmd[0])
+    try:
+        result = subprocess.run(cmd)
+    finally:
+        _copy_auth_file(
+            project_auth_path,
+            home_auth_path,
+            "project config -> global config",
+        )
+    return result.returncode

shell_scripts/commands/copilot.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""@brief GitHub Copilot CLI launcher in project context.
+
+@details Ensures project-root prerequisite and executable availability before
+blocking subprocess invocation of `copilot`.
+@satisfies REQ-015, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+## @var PROGRAM
+#  @brief Base CLI program name used in help output.
+#  @details Constant identifier for usage-line rendering in command help.
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief One-line command description for dispatcher help surfaces.
+#  @details Exposed by command registry introspection (`get_all_commands`).
+DESCRIPTION = "Launch GitHub Copilot CLI in the project context."
+
+
+def print_help(version):
+    """@brief Print command-specific help for `copilot`.
+
+    @details Emits usage and pass-through argument behavior for deterministic
+    terminal rendering; does not mutate process state.
+    @param version {str} CLI version string propagated by dispatcher.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+
+    print(f"Usage: {PROGRAM} copilot [args...] ({version})")
+    print()
+    print("copilot options:")
+    print("  All arguments are passed through to the Copilot CLI.")
+    print("  --help  - Show this help message.")
+
+
+def run(args):
+    """@brief Launch Copilot CLI after external executable validation.
+
+    @details Resolves project root, checks executable availability for
+    `copilot`, then executes pass-through args through blocking subprocess run.
+    @param args {list[str]} Additional CLI args forwarded to Copilot.
+    @return {int} Child process return code.
+    @satisfies REQ-015, REQ-055, REQ-056, REQ-064
+    """
+
+    require_project_root()
+    cmd = ["copilot", "--yolo", "--allow-all-tools", "--no-auto-update"] + args
+    cmd[0] = require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/dicom2jpg.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""@brief PixelMed DICOM-to-JPEG converter launcher.
+
+@details Resolves Java runtime and classpath prerequisites and validates Java
+executable availability before subprocess invocation.
+@satisfies REQ-026, REQ-055, REQ-056
+"""
+
+import os
+import subprocess
+import shutil
+
+from shell_scripts.utils import print_error, require_commands
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Convert DICOM images to JPEG using PixelMed."
+
+JAVA_WRAPPERS = "/usr/lib/java-wrappers/java-wrappers.sh"
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} dicom2jpg <input.dcm> <output.jpg> ({version})")
+    print()
+    print("dicom2jpg options:")
+    print("  <input.dcm>   - Input DICOM file (required).")
+    print("  <output.jpg>  - Output JPEG file (required).")
+    print("  --help        - Show this help message.")
+
+
+def _find_java():
+    for java in ("java", "/usr/bin/java"):
+        if shutil.which(java):
+            return java
+    return None
+
+
+def _find_jars(*jar_names):
+    jar_dirs = ["/usr/share/java", "/usr/local/share/java"]
+    found = []
+    for name in jar_names:
+        for d in jar_dirs:
+            jar_path = os.path.join(d, f"{name}.jar")
+            if os.path.exists(jar_path):
+                found.append(jar_path)
+                break
+    return found
+
+
+def run(args):
+    """@brief Run PixelMed converter after executable validation.
+
+    @details Validates Java runtime availability and command executability for
+    the selected Java binary before invoking conversion class.
+    @param args {list[str]} Expected `[input_dicom, output_jpeg]` arguments.
+    @return {int} Subprocess return code.
+    @satisfies REQ-026, REQ-055, REQ-056
+    """
+
+    if len(args) < 2:
+        print_error("Usage: dicom2jpg <input.dcm> <output.jpg>")
+        return 1
+
+    input_file = args[0]
+    output_file = args[1]
+
+    if not os.path.exists(JAVA_WRAPPERS):
+        print_error("java-wrappers not found. Install the 'java-wrappers' package.")
+        return 1
+
+    java = _find_java()
+    if not java:
+        print_error("Java runtime not found.")
+        return 1
+
+    jars = _find_jars(
+        "pixelmed",
+        "hsqldb",
+        "vecmath",
+        "jmdns",
+        "commons-codec",
+        "jai_imageio",
+        "clibwrapper_jiio",
+    )
+    classpath = ":".join(jars) if jars else ""
+
+    cmd = [
+        java,
+        "-Djava.awt.headless=true",
+        "-cp",
+        classpath,
+        "com.pixelmed.display.ConsumerFormatImageMaker",
+        input_file,
+        output_file,
+    ]
+
+    require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/dicomviewer.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""@brief PixelMed DICOM viewer launcher.
+
+@details Resolves Java runtime and classpath prerequisites and validates Java
+executable availability before subprocess invocation.
+@satisfies REQ-025, REQ-055, REQ-056
+"""
+
+import os
+import subprocess
+import shutil
+
+from shell_scripts.utils import print_error, require_commands
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Launch PixelMed DICOM image viewer."
+
+JAVA_WRAPPERS = "/usr/lib/java-wrappers/java-wrappers.sh"
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} dicomviewer [files...] ({version})")
+    print()
+    print("dicomviewer options:")
+    print("  [files...]  - DICOM files to view.")
+    print("  --help      - Show this help message.")
+
+
+def _find_java():
+    for java in ("java", "/usr/bin/java"):
+        if shutil.which(java):
+            return java
+    return None
+
+
+def _find_jars(*jar_names):
+    jar_dirs = ["/usr/share/java", "/usr/local/share/java"]
+    found = []
+    for name in jar_names:
+        for d in jar_dirs:
+            jar_path = os.path.join(d, f"{name}.jar")
+            if os.path.exists(jar_path):
+                found.append(jar_path)
+                break
+    return found
+
+
+def run(args):
+    """@brief Run PixelMed DICOM viewer after executable validation.
+
+    @details Validates Java runtime availability and command executability for
+    the selected Java binary before invoking the viewer class.
+    @param args {list[str]} DICOM file arguments forwarded to PixelMed viewer.
+    @return {int} Subprocess return code.
+    @satisfies REQ-025, REQ-055, REQ-056
+    """
+
+    if not os.path.exists(JAVA_WRAPPERS):
+        print_error(
+            "java-wrappers not found. Install the 'java-wrappers' package."
+        )
+        return 1
+
+    java = _find_java()
+    if not java:
+        print_error("Java runtime not found.")
+        return 1
+
+    jars = _find_jars(
+        "pixelmed", "hsqldb", "vecmath", "jmdns",
+        "commons-codec", "jai_imageio", "clibwrapper_jiio"
+    )
+    classpath = ":".join(jars) if jars else ""
+
+    cmd = [
+        java, "-Djava.awt.headless=true",
+        "-cp", classpath,
+        "com.pixelmed.display.DicomImageViewer",
+    ] + args
+
+    require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/diff_cmd.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""@brief MIME-based diff command wrapper.
+
+@details Exposes the `diff` CLI command and delegates category-based executable
+selection to shared `_dc_common.dispatch` logic.
+@satisfies PRJ-003, DES-007, REQ-023, REQ-024
+"""
+
+import sys
+
+from shell_scripts.config import get_dispatch_profile
+from shell_scripts.commands._dc_common import dispatch
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "File differ dispatcher by MIME type."
+
+
+def print_help(version):
+    """@brief Render command help for `diff`.
+
+    @details Prints usage, required file argument semantics, and argument
+    forwarding contract for the selected external diff executable.
+    @param version {str} Version string appended in usage output.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+    print(f"Usage: {PROGRAM} diff <file> [args...] ({version})")
+    print()
+    print("diff options:")
+    print("  <file>   - File to diff (required).")
+    print("  Additional arguments are passed to the selected diff tool.")
+    print("  --help   - Show this help message.")
+
+
+def run(args):
+    """@brief Execute MIME-routed diff dispatch.
+
+    @details Validates that a file argument exists; on missing argument prints
+    error plus help and returns status code `2`; otherwise resolves runtime
+    dispatch profile and delegates by file category through shared `_dc_common`.
+    @param args {list[str]} CLI args where `args[0]` is file path.
+    @return {int} Return code `2` on missing file; otherwise delegated dispatch result.
+    @satisfies REQ-023, REQ-024
+    """
+    if not args:
+        print("Error: file argument required.", file=sys.stderr)
+        print_help("")
+        return 2
+    category_cmds, fallback = get_dispatch_profile("diff")
+    return dispatch(category_cmds, fallback, args[0], args[1:])