shellscripts 0.23.1__py3-none-any.whl

shell_scripts/commands/ubuntu_dark_theme.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+"""@brief GNOME/Qt dark-theme configurator.
+
+@details Conditionally executes available theme helper executables and validates
+each executable immediately before invocation.
+@satisfies REQ-022, REQ-055, REQ-056
+"""
+import subprocess
+
+from shell_scripts.utils import print_info, command_exists, print_error, require_commands
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Apply GNOME and Qt dark theme settings."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} ubuntu-dark-theme ({version})")
+    print()
+    print("ubuntu-dark-theme options:")
+    print("  --help  - Show this help message.")
+    print()
+    print("Applies Adwaita-dark GTK theme via gsettings, then launches")
+    print("gtk-chtheme, qt5ct, and qt6ct for further customization.")
+
+
+def run(args):
+    """@brief Apply dark-theme settings with conditional executable checks.
+
+    @details For each available theme tool (`gsettings`, `gtk-chtheme`, `qt5ct`,
+    `qt6ct`), validates command executability before subprocess invocation.
+    @param args {list[str]} Unused command arguments.
+    @return {int} `0` on completion.
+    @satisfies REQ-022, REQ-055, REQ-056
+    """
+
+    print_info("Configure Adwaita-dark")
+
+    if command_exists("gsettings"):
+        require_commands("gsettings")
+        subprocess.run([
+            "gsettings", "set", "org.gnome.desktop.interface",
+            "gtk-theme", "Adwaita-dark",
+        ])
+    else:
+        print_error("gsettings not found.")
+
+    if command_exists("gtk-chtheme"):
+        require_commands("gtk-chtheme")
+        subprocess.run(["gtk-chtheme"])
+
+    import os
+    env5 = os.environ.copy()
+    env5["QT_QPA_PLATFORMTHEME"] = "qt5ct"
+    if command_exists("qt5ct"):
+        require_commands("qt5ct")
+        subprocess.run(["qt5ct"], env=env5)
+
+    env6 = os.environ.copy()
+    env6["QT_QPA_PLATFORMTHEME"] = "qt6ct"
+    if command_exists("qt6ct"):
+        require_commands("qt6ct")
+        subprocess.run(["qt6ct"], env=env6)
+
+    return 0

shell_scripts/commands/venv_cmd.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""@brief Virtual-environment recreation workflow with optional dependency install.
+
+@details Ensures required Python executables are available for the active flow
+before creating `.venv` and optionally running `pip install -r requirements.txt`.
+@satisfies REQ-038, REQ-055, REQ-056
+"""
+
+import os
+import sys
+import shutil
+import subprocess
+
+from shell_scripts.utils import (
+    require_project_root,
+    print_info,
+    print_success,
+    require_commands,
+)
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Create or recreate Python virtual environment with requirements."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} venv [options] ({version})")
+    print()
+    print("venv options:")
+    print("  --force  - Force recreation even if .venv exists.")
+    print("  --help   - Show this help message.")
+
+
+def run(args):
+    """@brief Recreate virtual environment with executable pre-checks.
+
+    @details Validates `sys.executable` and flow-conditional `pip` executable
+    before corresponding subprocess invocations.
+    @param args {list[str]} Command arguments (`--force` accepted).
+    @return {int} `0` on successful execution.
+    @satisfies REQ-038, REQ-055, REQ-056
+    """
+
+    force = "--force" in args
+    require_commands(sys.executable)
+    project_root = require_project_root()
+    os.chdir(project_root)
+
+    print(f"Run on path: {project_root}")
+
+    venv_dir = project_root / ".venv"
+
+    if venv_dir.is_dir():
+        if force:
+            print_info("Removing old virtual environment...")
+            shutil.rmtree(venv_dir)
+        else:
+            print_info("Removing old virtual environment...")
+            shutil.rmtree(venv_dir)
+
+    print_info("Creating virtual environment...")
+    subprocess.run(
+        [sys.executable, "-m", "venv", str(venv_dir)],
+        check=True,
+    )
+    print_success("Virtual environment created.")
+
+    pip = str(venv_dir / "bin" / "pip")
+    req_file = project_root / "requirements.txt"
+
+    if req_file.exists():
+        require_commands(pip)
+        print_info("Installing python requirements...")
+        subprocess.run(
+            [pip, "install", "-r", str(req_file)],
+            stdout=subprocess.DEVNULL,
+            check=True,
+        )
+        print_success("Requirements installed.")
+    else:
+        print_info("No requirements.txt found, skipping pip install.")
+
+    return 0

shell_scripts/commands/video2h264.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""@brief FFmpeg-based H.264 MP4 transcoder command.
+
+@details Converts one input video to H.264/AAC MP4 using fixed FFmpeg
+arguments required by CLI contract. Output path is generated by appending
+`.mp4` to the input filename and preserving the input directory.
+@satisfies REQ-057, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+from pathlib import Path
+
+from shell_scripts.utils import print_error, require_commands
+
+## @var PROGRAM
+#  @brief CLI program identifier used in usage text.
+#  @satisfies DES-008
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief Command description exposed in global help index.
+#  @satisfies PRJ-002, DES-008, REQ-057
+DESCRIPTION = "Convert one video to H.264 MP4 via ffmpeg."
+
+
+def print_help(version):
+    """@brief Print command usage for `video2h264`.
+
+    @details Emits deterministic help text describing required positional input
+    and output naming semantics.
+    @param version {str} CLI version string for usage suffix.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008, REQ-057
+    """
+
+    print(f"Usage: {PROGRAM} video2h264 <input-video> ({version})")
+    print()
+    print("video2h264 options:")
+    print("  <input-video>  - Input video file path (required).")
+    print("  --help         - Show this help message.")
+    print()
+    print("Output path is generated as <input-video>.mp4 in the input directory.")
+
+
+def run(args):
+    """@brief Execute H.264 transcode command with fixed FFmpeg parameters.
+
+    @details Validates input argument presence and file existence, then executes
+    `ffmpeg` using required libx264 profile, level, CRF, pixel format, and AAC
+    audio bitrate options through blocking subprocess invocation.
+    @param args {list[str]} Expected single positional input-video path.
+    @return {int} `1` on argument/validation failure; child return code otherwise.
+    @satisfies REQ-057, REQ-055, REQ-056, REQ-064
+    """
+
+    if len(args) != 1 or args[0].startswith("-"):
+        print_error("Input video file required.")
+        print_help("")
+        return 1
+
+    input_file = Path(args[0])
+    if not input_file.is_file():
+        print_error(f"File not found: {input_file}")
+        return 1
+
+    output_file = input_file.parent / f"{input_file.name}.mp4"
+    cmd = [
+        "ffmpeg",
+        "-i",
+        str(input_file),
+        "-c:v",
+        "libx264",
+        "-profile:v",
+        "high",
+        "-level",
+        "4.1",
+        "-crf",
+        "20",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "192k",
+        str(output_file),
+    ]
+
+    require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/video2h265.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""@brief FFmpeg-based H.265 MP4 transcoder command.
+
+@details Converts one input video to H.265/AAC MP4 using fixed FFmpeg
+arguments required by CLI contract. Output path is generated by appending
+`.mp4` to the input filename and preserving the input directory.
+@satisfies REQ-058, REQ-055, REQ-056, REQ-064
+"""
+
+import subprocess
+from pathlib import Path
+
+from shell_scripts.utils import print_error, require_commands
+
+## @var PROGRAM
+#  @brief CLI program identifier used in usage text.
+#  @satisfies DES-008
+PROGRAM = "shellscripts"
+## @var DESCRIPTION
+#  @brief Command description exposed in global help index.
+#  @satisfies PRJ-002, DES-008, REQ-058
+DESCRIPTION = "Convert one video to H.265 MP4 via ffmpeg."
+
+
+def print_help(version):
+    """@brief Print command usage for `video2h265`.
+
+    @details Emits deterministic help text describing required positional input
+    and output naming semantics.
+    @param version {str} CLI version string for usage suffix.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008, REQ-058
+    """
+
+    print(f"Usage: {PROGRAM} video2h265 <input-video> ({version})")
+    print()
+    print("video2h265 options:")
+    print("  <input-video>  - Input video file path (required).")
+    print("  --help         - Show this help message.")
+    print()
+    print("Output path is generated as <input-video>.mp4 in the input directory.")
+
+
+def run(args):
+    """@brief Execute H.265 transcode command with fixed FFmpeg parameters.
+
+    @details Validates input argument presence and file existence, then executes
+    `ffmpeg` using required libx265 CRF, codec tag, pixel format, and AAC audio
+    bitrate options through blocking subprocess invocation.
+    @param args {list[str]} Expected single positional input-video path.
+    @return {int} `1` on argument/validation failure; child return code otherwise.
+    @satisfies REQ-058, REQ-055, REQ-056, REQ-064
+    """
+
+    if len(args) != 1 or args[0].startswith("-"):
+        print_error("Input video file required.")
+        print_help("")
+        return 1
+
+    input_file = Path(args[0])
+    if not input_file.is_file():
+        print_error(f"File not found: {input_file}")
+        return 1
+
+    output_file = input_file.parent / f"{input_file.name}.mp4"
+    cmd = [
+        "ffmpeg",
+        "-i",
+        str(input_file),
+        "-c:v",
+        "libx265",
+        "-crf",
+        "23",
+        "-tag:v",
+        "hvc1",
+        "-pix_fmt",
+        "yuv420p",
+        "-c:a",
+        "aac",
+        "-b:a",
+        "192k",
+        str(output_file),
+    ]
+
+    require_commands(cmd[0])
+    result = subprocess.run(cmd)
+    return result.returncode

shell_scripts/commands/view_cmd.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""@brief MIME-based view command wrapper.
+
+@details Exposes the `view` 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 viewer dispatcher by MIME type."
+
+
+def print_help(version):
+    """@brief Render command help for `view`.
+
+    @details Prints usage, required file argument semantics, and argument
+    forwarding contract for the selected external viewer executable.
+    @param version {str} Version string appended in usage output.
+    @return {None} Writes help text to stdout.
+    @satisfies DES-008
+    """
+    print(f"Usage: {PROGRAM} view <file> [args...] ({version})")
+    print()
+    print("view options:")
+    print("  <file>   - File to view (required).")
+    print("  Additional arguments are passed to the selected viewer.")
+    print("  --help   - Show this help message.")
+
+
+def run(args):
+    """@brief Execute MIME-routed view 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("view")
+    return dispatch(category_cmds, fallback, args[0], args[1:])

shell_scripts/commands/vscode_cmd.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""@brief VS Code launcher in project context with Codex integration.
+
+@details Resolves project root, configures `CODEX_HOME`, validates VS Code
+executable availability, and performs blocking subprocess invocation.
+@satisfies REQ-020, REQ-021, REQ-055, REQ-056, REQ-064
+"""
+
+import os
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Open VS Code in the project root with Codex integration."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} vscode [args...] ({version})")
+    print()
+    print("vscode options:")
+    print("  [args...]  - Arguments passed through to VS Code.")
+    print("  --help     - Show this help message.")
+
+
+def run(args):
+    """@brief Launch VS Code after executable validation.
+
+    @details Sets `CODEX_HOME`, validates executable availability for VS Code
+    binary, and executes the command with project-root working directory.
+    @param args {list[str]} Additional CLI args forwarded to VS Code.
+    @return {int} Child process return code.
+    @satisfies REQ-020, REQ-021, REQ-055, REQ-056, REQ-064
+    """
+
+    project_root = require_project_root()
+    codex_home = str(project_root / ".codex")
+    os.environ["CODEX_HOME"] = codex_home
+    cmd = ["/usr/share/code/bin/code"] + args + [str(project_root)]
+    require_commands(cmd[0])
+    result = subprocess.run(cmd, cwd=project_root)
+    return result.returncode

shell_scripts/commands/vsinsider_cmd.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""@brief VS Code Insiders launcher in project context with Codex integration.
+
+@details Resolves project root, configures `CODEX_HOME`, validates VS Code
+Insiders executable availability, and performs blocking subprocess invocation.
+@satisfies REQ-020, REQ-021, REQ-055, REQ-056, REQ-064
+"""
+
+import os
+import subprocess
+
+from shell_scripts.utils import require_project_root, require_commands
+
+PROGRAM = "shellscripts"
+DESCRIPTION = "Open VS Code Insiders in the project root with Codex integration."
+
+
+def print_help(version):
+    print(f"Usage: {PROGRAM} vsinsider [args...] ({version})")
+    print()
+    print("vsinsider options:")
+    print("  [args...]  - Arguments passed through to VS Code Insiders.")
+    print("  --help     - Show this help message.")
+
+
+def run(args):
+    """@brief Launch VS Code Insiders after executable validation.
+
+    @details Sets `CODEX_HOME`, validates executable availability for VS Code
+    Insiders binary, and executes the command with project-root working directory.
+    @param args {list[str]} Additional CLI args forwarded to VS Code Insiders.
+    @return {int} Child process return code.
+    @satisfies REQ-020, REQ-021, REQ-055, REQ-056, REQ-064
+    """
+
+    project_root = require_project_root()
+    codex_home = str(project_root / ".codex")
+    os.environ["CODEX_HOME"] = codex_home
+    cmd = ["/usr/share/code-insiders/bin/code-insiders"] + args + [str(project_root)]
+    require_commands(cmd[0])
+    result = subprocess.run(cmd, cwd=project_root)
+    return result.returncode