shellscripts 0.23.1__py3-none-any.whl

shell_scripts/config.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""@brief Centralized runtime configuration loader and accessor surface.
+
+@details Stores hardcoded defaults for configurable CLI behaviors and provides
+deterministic runtime loading from `~/.config/shellScripts/config.json` with
+recursive merge semantics. Missing files/keys preserve defaults; invalid value
+types are ignored at accessor boundaries. Time complexity for load is O(N) over
+JSON node count.
+@satisfies DES-011, DES-012, REQ-004, REQ-005, REQ-024, REQ-045, REQ-046, REQ-050
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+from typing import Any
+
+from shell_scripts.utils import print_warn
+
+## @var DEFAULT_RUNTIME_CONFIG
+#  @brief Hardcoded default runtime configuration payload.
+#  @details Defines management command templates and dispatch command profiles
+#  for `diff`, `edit`, and `view`. Serialized by `write_default_runtime_config`.
+#  @satisfies DES-011, DES-012
+DEFAULT_RUNTIME_CONFIG: dict[str, Any] = {
+    "management": {
+        "upgrade": "uv tool install shellscripts --force",
+        "upgrade_develop": (
+            "uv tool install shellscripts --force "
+            "--from git+https://github.com/Ogekuri/shellScripts.git@{tag}"
+        ),
+        "uninstall": "uv tool uninstall shellscripts",
+    },
+    "dispatch": {
+        "diff": {
+            "categories": {
+                "image": ["bcompare"],
+                "pdf": ["bcompare"],
+                "text": ["bcompare"],
+                "code": ["bcompare"],
+                "html": ["bcompare"],
+                "markdown": ["bcompare"],
+            },
+            "fallback": ["bcompare"],
+        },
+        "edit": {
+            "categories": {
+                "image": ["gimp"],
+                "pdf": ["okular"],
+                "text": ["/opt/sublime_text/sublime_text", "--launch-or-new-window", "-wait"],
+                "code": ["/opt/sublime_text/sublime_text", "--launch-or-new-window", "-wait"],
+                "html": ["/opt/sublime_text/sublime_text", "--launch-or-new-window", "-wait"],
+                "markdown": ["/opt/sublime_text/sublime_text", "--launch-or-new-window", "-wait"],
+            },
+            "fallback": ["/opt/sublime_text/sublime_text", "-n", "-wait"],
+        },
+        "view": {
+            "categories": {
+                "image": ["sushi"],
+                "pdf": ["sushi"],
+                "text": ["sushi"],
+                "code": ["sushi"],
+                "html": ["sushi"],
+                "markdown": ["typora"],
+            },
+            "fallback": ["sushi"],
+        },
+    },
+    "req": {
+        "providers": [
+            "claude:prompts",
+            "github:skills",
+            "codex:skills",
+            "opencode:prompts",
+            "gemini:prompts",
+            "kiro:agents",
+            "pi:prompts",
+        ],
+        "static_checks": [
+            "C=Command,cppcheck,--error-exitcode=1,\"--enable=warning,style,performance,portability\",--std=c11",
+            "C=Command,clang-format,--dry-run,--Werror",
+            "C++=Command,cppcheck,--error-exitcode=1,\"--enable=warning,style,performance,portability\",--std=c++20",
+            "C++=Command,clang-format,--dry-run,--Werror",
+            "Python=Pylance",
+            "Python=Ruff",
+            "JavaScript=Command,node,--check",
+        ],
+    },
+}
+
+## @var _runtime_config
+#  @brief In-memory runtime configuration snapshot.
+#  @details Initialized from defaults; updated only by `load_runtime_config`.
+#  @satisfies DES-011, REQ-045
+_runtime_config: dict[str, Any] = copy.deepcopy(DEFAULT_RUNTIME_CONFIG)
+
+
+def get_config_path() -> Path:
+    """@brief Return canonical runtime config location.
+
+    @details Resolves path as `$HOME/.config/shellScripts/config.json` using
+    `Path.home()` for user directory abstraction.
+    @return {Path} Absolute config file path.
+    @satisfies DES-011, DES-012, REQ-045, REQ-046
+    """
+
+    return Path.home() / ".config" / "shellScripts" / "config.json"
+
+
+def get_default_runtime_config() -> dict[str, Any]:
+    """@brief Return deep-copied default configuration payload.
+
+    @details Produces an isolated copy to avoid external mutation of the global
+    defaults constant and to keep write/load operations deterministic.
+    @return {dict[str, Any]} Fresh deep copy of `DEFAULT_RUNTIME_CONFIG`.
+    @satisfies DES-011, DES-012
+    """
+
+    return copy.deepcopy(DEFAULT_RUNTIME_CONFIG)
+
+
+def _deep_merge_dict(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """@brief Recursively merge nested mapping values.
+
+    @details For keys where both base and override values are dictionaries,
+    recursively merges child keys; otherwise replaces base value with override.
+    Time complexity O(N) over override node count.
+    @param base {dict[str, Any]} Target mapping mutated in place.
+    @param override {dict[str, Any]} Source mapping with overriding values.
+    @return {dict[str, Any]} The mutated `base` reference.
+    @satisfies DES-011, REQ-045
+    """
+
+    for key, value in override.items():
+        if isinstance(base.get(key), dict) and isinstance(value, dict):
+            _deep_merge_dict(base[key], value)
+            continue
+        base[key] = value
+    return base
+
+
+def _normalize_command_vector(value: Any) -> list[str] | None:
+    """@brief Validate and normalize an executable argv vector.
+
+    @details Accepts only non-empty lists of non-empty strings and returns a
+    cloned list for defensive immutability.
+    @param value {Any} Candidate command vector.
+    @return {list[str]|None} Sanitized vector or `None` if invalid.
+    @satisfies DES-011, REQ-045
+    """
+
+    if not isinstance(value, list) or not value:
+        return None
+    if not all(isinstance(item, str) and item for item in value):
+        return None
+    return [item for item in value]
+
+
+def _normalize_string_list(value: Any) -> list[str] | None:
+    """@brief Validate and normalize a list of non-empty strings.
+
+    @details Accepts only list payloads containing non-empty string elements and
+    returns a cloned list for defensive immutability. Empty lists are valid.
+    @param value {Any} Candidate list payload.
+    @return {list[str]|None} Sanitized list or `None` if invalid.
+    @satisfies DES-011, REQ-045, REQ-050
+    """
+
+    if not isinstance(value, list):
+        return None
+    if not all(isinstance(item, str) and item for item in value):
+        return None
+    return [item for item in value]
+
+
+def _normalize_categories(value: Any) -> dict[str, list[str]] | None:
+    """@brief Validate category-to-command mapping payload.
+
+    @details Keeps only entries with string keys and valid command vectors.
+    Invalid entries are dropped and can trigger fallback usage upstream.
+    @param value {Any} Candidate category map payload.
+    @return {dict[str, list[str]]|None} Sanitized category map or `None`.
+    @satisfies DES-011, REQ-024, REQ-045
+    """
+
+    if not isinstance(value, dict):
+        return None
+    normalized: dict[str, list[str]] = {}
+    for key, command in value.items():
+        if not isinstance(key, str):
+            continue
+        command_vector = _normalize_command_vector(command)
+        if command_vector is None:
+            continue
+        normalized[key] = command_vector
+    return normalized
+
+
+def load_runtime_config(path: Path | None = None) -> dict[str, Any]:
+    """@brief Load runtime configuration file and merge into defaults.
+
+    @details Resets in-memory state to defaults for each call, then attempts to
+    read and parse JSON payload from target path and recursively merge override
+    keys. Missing file, invalid JSON, non-object root, or read errors preserve
+    defaults and emit warnings.
+    @param path {Path|None} Optional override path; default is canonical path.
+    @return {dict[str, Any]} Active in-memory runtime configuration snapshot.
+    @exception {json.JSONDecodeError} Handled internally and downgraded to warn.
+    @exception {OSError} Handled internally and downgraded to warn.
+    @satisfies DES-011, REQ-045
+    """
+
+    global _runtime_config
+
+    target = path or get_config_path()
+    _runtime_config = get_default_runtime_config()
+    if not target.exists():
+        return _runtime_config
+
+    try:
+        payload = json.loads(target.read_text(encoding="utf-8"))
+    except OSError as err:
+        print_warn(f"Cannot read runtime config '{target}': {err}. Using defaults.")
+        return _runtime_config
+    except json.JSONDecodeError as err:
+        print_warn(f"Invalid JSON in runtime config '{target}': {err}. Using defaults.")
+        return _runtime_config
+
+    if not isinstance(payload, dict):
+        print_warn(
+            f"Runtime config '{target}' must be a JSON object. Using defaults."
+        )
+        return _runtime_config
+
+    _deep_merge_dict(_runtime_config, payload)
+    return _runtime_config
+
+
+def get_management_command(name: str) -> str:
+    """@brief Resolve management command string with safe default fallback.
+
+    @details Reads runtime key under `management.<name>`; returns default value
+    when key is absent or not a non-empty string.
+    @param name {str} Management operation key (`upgrade` or `uninstall`).
+    @return {str} Shell command string to execute.
+    @satisfies REQ-004, REQ-005, REQ-045
+    """
+
+    runtime_value = _runtime_config.get("management", {}).get(name)
+    if isinstance(runtime_value, str) and runtime_value.strip():
+        return runtime_value
+    default_value = DEFAULT_RUNTIME_CONFIG["management"][name]
+    return default_value
+
+
+def get_dispatch_profile(name: str) -> tuple[dict[str, list[str]], list[str]]:
+    """@brief Resolve dispatch profile for diff/edit/view command wrappers.
+
+    @details Builds profile from `dispatch.<name>` runtime payload with typed
+    normalization and per-section fallback to hardcoded defaults for missing or
+    invalid values.
+    @param name {str} Dispatch command key (`diff`, `edit`, or `view`).
+    @return {tuple[dict[str, list[str]], list[str]]} `(categories, fallback)`.
+    @satisfies DES-007, REQ-024, REQ-045
+    """
+
+    default_profile = DEFAULT_RUNTIME_CONFIG["dispatch"][name]
+    runtime_profile = _runtime_config.get("dispatch", {}).get(name, {})
+
+    categories = _normalize_categories(runtime_profile.get("categories"))
+    if categories is None:
+        categories = _normalize_categories(default_profile["categories"])
+    fallback = _normalize_command_vector(runtime_profile.get("fallback"))
+    if fallback is None:
+        fallback = _normalize_command_vector(default_profile["fallback"])
+
+    if categories is None or fallback is None:
+        raise ValueError("Default dispatch profile is invalid.")
+    return categories, fallback
+
+
+def get_req_profile() -> tuple[list[str], list[str]]:
+    """@brief Resolve `req` providers and static checks from runtime config.
+
+    @details Builds profile from `req.providers` and `req.static_checks` runtime
+    payload with typed normalization and per-section fallback to hardcoded
+    defaults for missing or invalid values.
+    @return {tuple[list[str], list[str]]} `(providers, static_checks)`.
+    @satisfies DES-011, REQ-045, REQ-050
+    """
+
+    default_profile = DEFAULT_RUNTIME_CONFIG["req"]
+    runtime_profile = _runtime_config.get("req", {})
+    if not isinstance(runtime_profile, dict):
+        runtime_profile = {}
+
+    providers = _normalize_string_list(runtime_profile.get("providers"))
+    if providers is None:
+        providers = _normalize_string_list(default_profile["providers"])
+
+    static_checks = _normalize_string_list(runtime_profile.get("static_checks"))
+    if static_checks is None:
+        static_checks = _normalize_string_list(default_profile["static_checks"])
+
+    if providers is None or static_checks is None:
+        raise ValueError("Default req profile is invalid.")
+    return providers, static_checks
+
+
+def write_default_runtime_config(path: Path | None = None) -> Path:
+    """@brief Write default runtime configuration file to disk.
+
+    @details Creates parent directories when missing and writes canonical JSON
+    payload using sorted keys and indentation for deterministic content.
+    @param path {Path|None} Optional override path; default is canonical path.
+    @return {Path} Path where the file has been written.
+    @exception {OSError} Propagated when filesystem write fails.
+    @satisfies DES-012, REQ-046
+    """
+
+    target = path or get_config_path()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        f"{json.dumps(DEFAULT_RUNTIME_CONFIG, indent=2, sort_keys=True)}\n",
+        encoding="utf-8",
+    )
+    return target

shell_scripts/core.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""@brief Main shellscripts CLI dispatcher and management operation handler.
+
+@details Provides global help rendering, management command execution
+(`--version`, `--ver`, `--upgrade`, `--uninstall`, `--write-config`,
+`--develop`/`--dev` upgrade selector), runtime
+configuration bootstrap, and subcommand delegation to lazily imported modules.
+@satisfies PRJ-001, PRJ-002, PRJ-003, REQ-001, REQ-002, REQ-003, REQ-004, REQ-005, REQ-045, REQ-046, REQ-048, REQ-049, REQ-050, REQ-051, REQ-052, REQ-053, REQ-054, REQ-056, REQ-064, REQ-065, REQ-066, REQ-068, REQ-069, REQ-075, REQ-076, REQ-077, REQ-078
+"""
+
+import sys
+import subprocess
+
+from shell_scripts import __version__
+from shell_scripts.config import (
+    get_management_command,
+    load_runtime_config,
+    write_default_runtime_config,
+)
+from shell_scripts.version_check import check_for_updates, fetch_github_latest_release, print_remote_latest_versions
+from shell_scripts.commands import get_command
+from shell_scripts.utils import (
+    capture_terminal_state,
+    detect_runtime_os,
+    is_linux,
+    print_error,
+    print_info,
+    reset_terminal_state,
+    require_shell_command_executables,
+)
+
+PROGRAM = "shellscripts"
+## @var HELP_COMMAND_COLUMN_WIDTH
+#  @brief Fixed command-name column width for grouped help rendering.
+#  @details Forces deterministic spacing for all command rows across grouped
+#  global help sections.
+#  @satisfies REQ-066
+HELP_COMMAND_COLUMN_WIDTH = 16
+
+## @var HELP_SECTION_COMMANDS
+#  @brief Ordered command groups for global help rendering.
+#  @details Defines deterministic section order and command-token order used by
+#  `print_help` when emitting grouped command help. Ordering is normative and
+#  maps directly to REQ-066 output expectations.
+#  @satisfies DES-014, REQ-066
+HELP_SECTION_COMMANDS = (
+    (
+        "Edit/View Commands",
+        (
+            "edit",
+            "view",
+            "diff",
+        ),
+    ),
+    (
+        "PDF Commands",
+        (
+            "pdf-crop",
+            "pdf-merge",
+            "pdf-split-by-format",
+            "pdf-split-by-toc",
+            "pdf-tiler-090",
+            "pdf-tiler-100",
+            "pdf-toc-clean",
+        ),
+    ),
+    (
+        "AI Commands",
+        (
+            "ai-install",
+            "claude",
+            "codex",
+            "copilot",
+            "gemini",
+            "kiro",
+            "opencode",
+            "pi",
+        ),
+    ),
+    (
+        "Develop Commands",
+        (
+            "req",
+            "venv",
+            "clean",
+            "doxygen",
+            "tests",
+            "vscode",
+            "vsinsider",
+        ),
+    ),
+    (
+        "Image Commands",
+        (
+            "dicom2jpg",
+            "dicomviewer",
+        ),
+    ),
+    (
+        "Video Commands",
+        (
+            "video2h264",
+            "video2h265",
+        ),
+    ),
+    (
+        "OS Commands",
+        ("ubuntu-dark-theme",),
+    ),
+)
+
+
+def print_help(command_name=None):
+    """@brief Print global or command-specific help text.
+
+    @details Renders command module help for known command names; otherwise exits
+    with explicit unknown-command error. Global help includes management options
+    and grouped command sections using deterministic section and command order,
+    with descriptions sourced from each command module `DESCRIPTION` constant.
+    @param command_name {str|None} Optional command token for scoped help.
+    @return {None} Writes to stdout/stderr; may terminate process on invalid command.
+    @throws {SystemExit} Raised when unknown command name is requested.
+    @satisfies PRJ-002, DES-014, REQ-001, REQ-002, REQ-066, REQ-068, REQ-069
+    """
+
+    if command_name:
+        cmd = get_command(command_name)
+        if cmd:
+            cmd.print_help(__version__)
+        else:
+            print_error(f"Unknown command: {command_name}")
+            sys.exit(1)
+        return
+
+    print(f"Usage: {PROGRAM} [command] [options] ({__version__})")
+    print()
+    print("Management Commands:")
+    print(
+        f"  --upgrade    - Reinstall {PROGRAM} on Linux; print manual command elsewhere."
+    )
+    print(
+        "  --dev        - With --upgrade: upgrade from the latest GitHub release tag"
+    )
+    print("                 instead of PyPI (alias: --develop).")
+    print(
+        f"  --uninstall  - Uninstall {PROGRAM} on Linux; print manual command elsewhere."
+    )
+    print("  --write-config - Write default runtime config to user config directory.")
+    print(
+        f"  --ver        - Print the {PROGRAM} version plus latest PyPI and GitHub versions."
+    )
+    print(
+        f"  --version    - Print the {PROGRAM} version plus latest PyPI and GitHub versions."
+    )
+    print(
+        "  --help       - Print the full help screen or the help text of a specific command."
+    )
+    print()
+    for section_name, command_names in HELP_SECTION_COMMANDS:
+        print()
+        print(section_name)
+        for command_name in command_names:
+            command_module = get_command(command_name)
+            description = getattr(command_module, "DESCRIPTION", "")
+            print(f"  {command_name:<{HELP_COMMAND_COLUMN_WIDTH}} - {description}")
+
+
+def _build_develop_upgrade_command(latest_tag: str) -> str:
+    """@brief Compose the develop upgrade command for one GitHub release tag.
+
+    @details Resolves the `management.upgrade_develop` runtime-config template,
+    substitutes the `{tag}` placeholder with the supplied tag, and returns the
+    shell command that installs the package from the GitHub tag archive.
+    Complexity O(n) over template length.
+    @param latest_tag {str} GitHub release tag token preserving its `v` prefix.
+    @return {str} Fully substituted shell upgrade command.
+    @satisfies REQ-076, DES-019
+    """
+
+    template = get_management_command("upgrade_develop")
+    return template.replace("{tag}", latest_tag)
+
+
+def do_upgrade(develop: bool = False) -> int:
+    """@brief Execute Linux-only upgrade command resolved from runtime config.
+
+    @details Reads management command string from runtime config key
+    `management.upgrade` (PyPI default) or, when `develop` is set, resolves
+    the latest GitHub release tag and composes the tag-pinned upgrade command;
+    executes it on Linux via shell invocation and prints the manual fallback
+    command on non-Linux systems.
+    @param develop {bool} Force upgrade from the latest GitHub release tag.
+    @return {int} `1` when develop tag resolution fails; subprocess return code
+      on Linux; `0` on non-Linux fallback.
+    @satisfies REQ-004, REQ-076, REQ-078, REQ-045, REQ-056
+    """
+
+    if develop:
+        try:
+            latest_tag = fetch_github_latest_release(__version__)
+        except Exception as error:
+            print_error(f"GitHub latest release resolution failed: {error}.")
+            return 1
+        install_cmd = _build_develop_upgrade_command(latest_tag)
+    else:
+        install_cmd = get_management_command("upgrade")
+    if is_linux():
+        require_shell_command_executables(install_cmd)
+        print(f"Upgrading {PROGRAM}...")
+        result = subprocess.run(install_cmd, shell=True)
+        return result.returncode
+    else:
+        print(f"{PROGRAM} automatic upgrade is only supported on Linux.")
+        print("Run this command manually:")
+        print(f"  {install_cmd}")
+        return 0
+
+
+def do_uninstall():
+    """@brief Execute Linux-only uninstall command resolved from runtime config.
+
+    @details Reads management command string from runtime config key
+    `management.uninstall`, executes it on Linux via shell invocation, and
+    prints manual fallback command on non-Linux systems.
+    @return {int} Subprocess return code on Linux; `0` on non-Linux fallback.
+    @satisfies REQ-005, REQ-045, REQ-056
+    """
+
+    uninstall_cmd = get_management_command("uninstall")
+    if is_linux():
+        require_shell_command_executables(uninstall_cmd)
+        print(f"Uninstalling {PROGRAM}...")
+        result = subprocess.run(uninstall_cmd, shell=True)
+        return result.returncode
+    else:
+        print(f"{PROGRAM} automatic uninstall is only supported on Linux.")
+        print("Run this command manually:")
+        print(f"  {uninstall_cmd}")
+        return 0
+
+
+def do_write_config():
+    """@brief Persist default runtime configuration file to disk.
+
+    @details Writes canonical config JSON to
+    `$HOME/.config/shellScripts/config.json` and logs destination path.
+    @return {int} `0` on successful write.
+    @throws {OSError} Propagated on filesystem write failure.
+    @satisfies REQ-046
+    """
+
+    target = write_default_runtime_config()
+    target_text = target.as_posix() if hasattr(target, "as_posix") else str(target)
+    print_info(f"Default runtime config written to: {target_text}")
+    return 0
+
+
+def main():
+    """@brief Entrypoint for shellscripts argument dispatch.
+
+    @details Performs runtime OS detection, update check, runtime configuration
+    load, and argument dispatch through management flags (`--version` prints
+    installed plus PyPI/GitHub latest versions; `--upgrade` upgrades from PyPI
+    or, with `--develop`/`--dev`, from the latest GitHub release tag) and
+    subcommands, then restores terminal raw/cbreak and disables legacy+xterm
+    mouse-tracking modes (`?9l`, `?1000l`, `?1001l`, `?1002l`, `?1003l`,
+    `?1004l`, `?1005l`, `?1006l`, `?1007l`, `?1015l`, `?1016l`) before exit.
+    @return {int} Process-compatible return code for caller (`sys.exit`).
+    @satisfies PRJ-001, REQ-001, REQ-002, REQ-003, REQ-004, REQ-005, REQ-045, REQ-046, REQ-047, REQ-048, REQ-049, REQ-050, REQ-051, REQ-052, REQ-053, REQ-054, REQ-064, REQ-065, REQ-066, REQ-068, REQ-069, REQ-075, REQ-076, REQ-077, REQ-078
+    """
+    saved_tty = capture_terminal_state()
+    try:
+        detect_runtime_os()
+        check_for_updates(__version__)
+        load_runtime_config()
+
+        args = sys.argv[1:]
+
+        if not args:
+            print_help()
+            return 0
+
+        first_arg = args[0]
+
+        if first_arg in ("--version", "--ver"):
+            print(__version__)
+            print_remote_latest_versions(__version__)
+            return 0
+
+        if first_arg == "--upgrade":
+            develop = any(arg in ("--develop", "--dev") for arg in args[1:])
+            return do_upgrade(develop=develop)
+
+        if first_arg in ("--develop", "--dev"):
+            print_error("--develop/--dev must be used together with --upgrade.")
+            return 1
+
+        if first_arg == "--uninstall":
+            return do_uninstall()
+
+        if first_arg == "--write-config":
+            return do_write_config()
+
+        if first_arg == "--help":
+            if len(args) > 1:
+                print_help(args[1])
+            else:
+                print_help()
+            return 0
+
+        cmd = get_command(first_arg)
+        if cmd:
+            cmd_args = args[1:]
+            if "--help" in cmd_args:
+                cmd.print_help(__version__)
+                return 0
+            return cmd.run(cmd_args) or 0
+
+        print_error(f"Unknown command: {first_arg}")
+        print()
+        print_help()
+        return 1
+    finally:
+        reset_terminal_state(saved_tty)