shellscripts 0.23.1__py3-none-any.whl

shell_scripts/version_check.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""@brief Update-check orchestration for shellscripts startup.
+
+@details Performs cooldown-gated PyPI registry checks for the startup update
+notification, resolves GitHub release tags for develop upgrades and version
+display, persists cache metadata for every request outcome, and prints
+terminal-visible update or error status lines. Successful requests apply the
+default cooldown. Request errors apply the enlarged cooldown without aborting
+CLI startup continuity.
+@satisfies PRJ-004, DES-002, DES-003, DES-004, DES-005, DES-006, DES-018, DES-019, DES-020, REQ-003, REQ-075, REQ-059, REQ-060, REQ-061
+"""
+
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+PROGRAM = "shellscripts"
+OWNER = "Ogekuri"
+REPOSITORY = "shellScripts"
+IDLE_DELAY = 3600
+HTTP_ERROR_IDLE_DELAY = 86400
+HTTP_TIMEOUT = 2
+GITHUB_API_URL = f"https://api.github.com/repos/{OWNER}/{REPOSITORY}/releases/latest"
+PYPI_API_URL = f"https://pypi.org/pypi/{PROGRAM}/json"
+CACHE_DIR = Path.home() / ".cache" / PROGRAM
+IDLE_TIME_FILE = CACHE_DIR / "check_version_idle-time.json"
+
+BRIGHT_GREEN = "\033[92m"
+BRIGHT_RED = "\033[91m"
+RESET = "\033[0m"
+
+
+def _read_idle_config() -> dict[str, object] | None:
+    """@brief Load cached cooldown metadata for the version check.
+
+    @details Reads the cooldown JSON payload from the user cache directory.
+    Absent files and unreadable JSON payloads resolve to `None`. Complexity:
+    O(1) for fixed-size payload parsing.
+    @return {dict[str, object] | None} Cached cooldown payload or `None`.
+    @satisfies DES-003, REQ-059
+    """
+
+    if not IDLE_TIME_FILE.exists():
+        return None
+    try:
+        with open(IDLE_TIME_FILE) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def _write_idle_config(last_check_ts: float, idle_delay_seconds: int) -> None:
+    """@brief Persist cooldown timestamps for the next version-check gate.
+
+    @details Derives the idle-until timestamp from the supplied delay, writes
+    both machine-readable timestamps and UTC-rendered strings, and stores the
+    applied delay for downstream inspection. Complexity: O(1).
+    @param last_check_ts {float} UNIX timestamp recorded for the current check.
+    @param idle_delay_seconds {int} Cooldown duration applied after the check.
+    @return {None} No return value.
+    @throws {OSError} Propagated when cache directory creation or file write fails.
+    @satisfies DES-003, DES-004, DES-005, REQ-061
+    """
+
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    idle_until_ts = last_check_ts + idle_delay_seconds
+    data = {
+        "last_check_timestamp": last_check_ts,
+        "last_check_human": datetime.fromtimestamp(
+            last_check_ts, tz=timezone.utc
+        ).strftime("%Y-%m-%d %H:%M:%S UTC"),
+        "idle_delay_seconds": idle_delay_seconds,
+        "idle_until_timestamp": idle_until_ts,
+        "idle_until_human": datetime.fromtimestamp(
+            idle_until_ts, tz=timezone.utc
+        ).strftime("%Y-%m-%d %H:%M:%S UTC"),
+    }
+    with open(IDLE_TIME_FILE, "w") as f:
+        json.dump(data, f, indent=2)
+
+
+def _is_forced_version_check() -> bool:
+    """@brief Detect CLI flags that force the version-check HTTP request.
+
+    @details Evaluates the live process argument vector and returns `True` when
+    the current invocation requested `--version` or `--ver`. Complexity: O(N)
+    where N is the number of CLI arguments.
+    @return {bool} `True` when the request must bypass cooldown gating.
+    @satisfies REQ-003, REQ-059
+    """
+
+    return any(arg in ("--version", "--ver") for arg in sys.argv[1:])
+
+
+def _format_request_error(error: Exception) -> str:
+    """@brief Convert a request exception into terminal output detail text.
+
+    @details Returns a stable, parser-friendly error descriptor for HTTP and
+    non-HTTP request failures. HTTP errors preserve the status code. Non-HTTP
+    errors expose the exception type and optional message. Complexity: O(1).
+    @param error {Exception} Request failure captured during update checking.
+    @return {str} Error detail suffix without terminal color codes.
+    @satisfies DES-005, DES-006, REQ-061
+    """
+
+    if isinstance(error, urllib.error.HTTPError):
+        if error.code in (403, 429):
+            return f"rate limit exceeded (HTTP {error.code})"
+        return f"HTTP {error.code}"
+
+    error_type = type(error).__name__
+    error_message = str(error).strip()
+    if error_message:
+        return f"{error_type}: {error_message}"
+    return error_type
+
+
+def _handle_request_error(last_check_ts: float, error: Exception) -> None:
+    """@brief Persist cooldown metadata and print the request error line.
+
+    @details Applies the fixed HTTP-error cooldown, updates the cooldown JSON,
+    and emits a bright-red terminal line for the supplied request failure.
+    Complexity: O(1) excluding filesystem latency.
+    @param last_check_ts {float} UNIX timestamp recorded for the failed check.
+    @param error {Exception} Request failure captured during update checking.
+    @return {None} No return value.
+    @throws {OSError} Propagated when cache directory creation or file write fails.
+    @satisfies DES-003, DES-005, DES-006, REQ-061
+    """
+
+    _write_idle_config(last_check_ts, HTTP_ERROR_IDLE_DELAY)
+    print(f"{BRIGHT_RED}Update check failed: {_format_request_error(error)}.{RESET}")
+
+
+def _should_check(force_check: bool = False) -> bool:
+    """@brief Evaluate whether the GitHub version-check request should run.
+
+    @details Forces execution when `force_check` is `True`; otherwise reads the
+    cached idle-until timestamp and compares it against the current wall-clock
+    time. Complexity: O(1).
+    @param force_check {bool} Cooldown-bypass flag derived from CLI arguments.
+    @return {bool} `True` when the HTTP request is allowed or forced.
+    @satisfies REQ-003, REQ-059
+    """
+
+    if force_check:
+        return True
+    config = _read_idle_config()
+    if config is None:
+        return True
+    idle_until = config.get("idle_until_timestamp", 0)
+    if not isinstance(idle_until, (int, float)):
+        return True
+    return time.time() >= idle_until
+
+
+def _parse_version(version_value: str) -> tuple[int, ...]:
+    """@brief Convert a semantic-version string into an integer tuple.
+
+    @details Strips a leading `v` prefix, splits by `.`, and converts each
+    segment to `int`. Complexity: O(N) where N is the number of segments.
+    @param version_value {str} Raw semantic version token.
+    @return {tuple[int, ...]} Parsed numeric version segments.
+    @throws {ValueError} Propagated when a segment is not numeric.
+    @satisfies PRJ-004
+    """
+
+    return tuple(int(part) for part in version_value.strip().lstrip("v").split("."))
+
+
+def _compare_versions(current: str, latest: str) -> bool:
+    """@brief Compare installed and latest semantic versions.
+
+    @details Parses both version strings into integer tuples and returns
+    `True` only when `latest` is newer than `current`. Invalid inputs collapse
+    to `False`. Complexity: O(N).
+    @param current {str} Installed package version.
+    @param latest {str} Latest GitHub release version.
+    @return {bool} `True` when the remote version is newer.
+    @satisfies PRJ-004, REQ-060
+    """
+
+    try:
+        return _parse_version(latest) > _parse_version(current)
+    except (ValueError, AttributeError):
+        return False
+
+
+def _fetch_json_payload(
+    url: str, current_version: str, accept_header: str
+) -> dict[str, Any]:
+    """@brief Fetch and decode one JSON payload over HTTP.
+
+    @details Issues a GET request with caller-supplied `Accept` header and a
+    program/version `User-Agent`, then decodes the response body as a JSON
+    object. Time complexity O(n) over payload size.
+    @param url {str} Remote JSON endpoint URL.
+    @param current_version {str} Installed package version used in User-Agent.
+    @param accept_header {str} Value of the HTTP `Accept` header.
+    @return {dict[str, Any]} Parsed JSON response object.
+    @throws {urllib.error.HTTPError} On HTTP error responses.
+    @throws {urllib.error.URLError} On connection failures.
+    @throws {json.JSONDecodeError} On malformed payload bodies.
+    @satisfies DES-018, DES-019
+    """
+
+    request = urllib.request.Request(url)
+    request.add_header("Accept", accept_header)
+    request.add_header("User-Agent", f"{PROGRAM}/{current_version}")
+    with urllib.request.urlopen(request, timeout=HTTP_TIMEOUT) as response:
+        return json.loads(response.read().decode())
+
+
+def fetch_pypi_latest_version(current_version: str) -> str:
+    """@brief Resolve the latest published version from the PyPI registry.
+
+    @details Queries the PyPI JSON API for this program and extracts field
+    `info.version`. Complexity O(1) over response object size.
+    @param current_version {str} Installed package version used in User-Agent.
+    @return {str} Latest published version token (for example `1.2.3`).
+    @throws {urllib.error.HTTPError} On HTTP error responses.
+    @throws {urllib.error.URLError} On connection failures.
+    @throws {json.JSONDecodeError} On malformed payload bodies.
+    @throws {KeyError} When `info.version` fields are absent.
+    @satisfies DES-018, PRJ-004
+    """
+
+    payload = _fetch_json_payload(
+        PYPI_API_URL, current_version, "application/vnd.pypi.simple.v1+json"
+    )
+    info = payload["info"]
+    return str(info["version"])
+
+
+def fetch_github_latest_release(current_version: str) -> str:
+    """@brief Resolve the latest GitHub release tag regardless of its branch.
+
+    @details Queries the GitHub Releases API `latest` endpoint and extracts
+    field `tag_name`, which tracks the newest published tagged release across
+    any branch. Complexity O(1) over response object size.
+    @param current_version {str} Installed package version used in User-Agent.
+    @return {str} Latest release tag token preserving its `v` prefix.
+    @throws {urllib.error.HTTPError} On HTTP error responses.
+    @throws {urllib.error.URLError} On connection failures.
+    @throws {json.JSONDecodeError} On malformed payload bodies.
+    @throws {KeyError} When `tag_name` field is absent.
+    @satisfies DES-019, REQ-076
+    """
+
+    payload = _fetch_json_payload(
+        GITHUB_API_URL, current_version, "application/vnd.github.v3+json"
+    )
+    return str(payload["tag_name"])
+
+
+def print_remote_latest_versions(current_version: str) -> None:
+    """@brief Print PyPI and GitHub latest-version report lines.
+
+    @details Emits one `<source> latest: <version>` line per remote source in
+    fixed order (PyPI, GitHub). A failed source lookup prints one bright-red
+    error line instead of its version line, and the remaining source is still
+    processed. Complexity O(1) excluding network latency.
+    @param current_version {str} Installed package version used in User-Agent.
+    @return {None} Writes two report or error lines to stdout.
+    @satisfies REQ-003, REQ-075, DES-020
+    """
+
+    for source_label, fetch_version in (
+        ("PyPI", fetch_pypi_latest_version),
+        ("GitHub", fetch_github_latest_release),
+    ):
+        try:
+            latest_version = fetch_version(current_version).lstrip("v")
+        except Exception as error:
+            print(
+                f"{BRIGHT_RED}{source_label} latest check failed: "
+                f"{_format_request_error(error)}.{RESET}"
+            )
+            continue
+        print(f"{source_label} latest: {latest_version}")
+
+
+def check_for_updates(current_version: str) -> None:
+    """@brief Execute the startup PyPI registry version check.
+
+    @details Applies cooldown gating unless the current CLI invocation requests
+    `--version` or `--ver`, performs the PyPI latest-version HTTP request,
+    prints a bright-green update line for newer releases, persists a
+    3600-second success cooldown or an 86400-second request-error cooldown for
+    every request outcome, prints bright-red request errors, and suppresses
+    propagation of non-HTTP request exceptions. Complexity O(1) excluding
+    network latency and JSON parsing.
+    @param current_version {str} Installed package version string.
+    @return {None} No return value.
+    @throws {urllib.error.HTTPError} Internally handled and converted to output.
+    @satisfies PRJ-004, DES-004, DES-005, DES-006, DES-018, REQ-003, REQ-059, REQ-060, REQ-061
+    """
+
+    if not _should_check(force_check=_is_forced_version_check()):
+        return
+
+    now = time.time()
+
+    try:
+        latest = fetch_pypi_latest_version(current_version)
+
+        if latest and _compare_versions(current_version, latest):
+            print(
+                f"{BRIGHT_GREEN}Versione Disponibile: {latest} | "
+                f"Versione Installata: {current_version}{RESET}"
+            )
+
+        _write_idle_config(now, IDLE_DELAY)
+
+    except urllib.error.HTTPError as error:
+        _handle_request_error(now, error)
+    except Exception as error:
+        _handle_request_error(now, error)

shellscripts-0.23.1.dist-info/METADATA

@@ -0,0 +1,310 @@
+Metadata-Version: 2.4
+Name: shellscripts
+Version: 0.23.1
+Summary: Execute useful shell scripts via an uvx-compatible CLI interface.
+Author: Francesco Rolando
+License-Expression: GPL-3.0-only
+Project-URL: Homepage, https://github.com/Ogekuri/shellScripts
+Project-URL: Repository, https://github.com/Ogekuri/shellScripts
+Keywords: shell,scripts,uv,astral,uvx,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+> [!CAUTION]
+> ### 🚨 STRICTLY EXPERIMENTAL — PROOF OF CONCEPT (PRE-ALPHA)
+> 
+> ![Status: Proof of Concept](https://img.shields.io/badge/Status-Proof_of_Concept-red?style=flat-square) ![Stage: Pre-Alpha](https://img.shields.io/badge/Stage-Pre--Alpha-critical?style=flat-square) ![Maintenance: Personal Use Only](https://img.shields.io/badge/Scope-Personal_Use_Only-important?style=flat-square) ![Issues: Closed](https://img.shields.io/badge/Issues_%26_PRs-Not_Accepted-inactive?style=flat-square)
+>
+> **PLEASE READ CAREFULLY BEFORE USING THIS SOFTWARE:**
+> 
+> * **Very Early Stage:** This project is currently a raw **Proof of Concept (PoC)** in a **pre-alpha** state. It is nowhere near production-ready and may contain severe bugs, breaking changes, or incomplete logic.
+> * **Personal Use Only:** This repository is developed, maintained, and shared strictly for **personal use**. 
+> * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
+> * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
+
+# s/shellScripts (0.23.1)
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-GPL--3.0-491?style=flat-square" alt="License: GPL-3.0">
+  <img src="https://img.shields.io/badge/platform-Linux-6A7EC2?style=flat-square&logo=terminal&logoColor=white" alt="Platforms">
+  <img src="https://img.shields.io/badge/docs-live-b31b1b" alt="Docs">
+<img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
+</p>
+<p align="center">
+<strong>Execute useful shell scripts via an uvx-compatible CLI interface.</strong><br>
+<code>shellscripts</code> is a Linux-first command collection for project automation, AI CLI launchers,
+PDF/DICOM utilities, development helpers, and editor integrations, exposed through a single command.
+<br>
+</p>
+
+
+<p align="center">
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#feature-highlights">Feature Highlights</a> |
+  <a href="#management-commands">Upgrading or Removing</a> |
+  <a href="#shell-scripts">Shell Scripts</a>
+</p>
+
+<p align="center">
+<br>
+🚧 <strong>DRAFT:</strong> Proof-of-Concept (PoC) Version 📝 - Work in Progress 🏗️ 🚧<br>
+⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://www.npmjs.com/package/pi-usereq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️<br>
+<br>
+</p>
+
+
+## Feature Highlights
+- Single CLI entrypoint with command dispatch and grouped built-in help (`shellscripts` and alias `s`).
+- AI tooling bootstrap command (`ai-install`) with per-tool selectors for Codex, Copilot, Gemini, OpenCode, Claude, and Kiro.
+- Project-context launchers for AI CLIs (`claude`, `codex`, `copilot`, `gemini`, `kiro`, `opencode`, `pi`) and IDEs (`vscode`, `vsinsider`).
+- PDF workflow commands for crop, merge, split, TOC cleanup, and tiling.
+- DICOM helpers (`dicom2jpg`, `dicomviewer`) and video transcoders (`video2h264`, `video2h265`).
+- Project maintenance and automation commands (`req`, `clean`, `venv`, `tests`, `doxygen`, `ubuntu-dark-theme`).
+- Startup update notification with rate-limited checks against the PyPI registry.
+
+
+## Requirements
+
+- Python `>=3.11`.
+- Astral `uv` is required for install and runtime flows (`uv tool install`, `uvx`, `uv run`).
+- Git is required for commands that enforce repository-root execution (`claude`, `codex`, `copilot`, `gemini`, `kiro`, `opencode`, `pi`, `clean`, `venv`, `tests`, `doxygen`, `vscode`, `vsinsider`).
+- Command-specific external tools are required only for related commands:
+  - `npm` (and `sudo` on non-Windows) for npm-based `ai-install` targets.
+  - `req` for the `req` command.
+  - `doxygen` (plus optional `make` and `pdflatex`) for `doxygen`.
+  - `gs`, `pdfinfo`, `qpdf`, `pdftk`, `plakativ` for PDF commands.
+  - `ffmpeg` for `video2h264` and `video2h265`.
+  - Java runtime + PixelMed jars (+ `java-wrappers`) for DICOM commands.
+
+
+## Quick Start
+
+### Prerequisites
+
+- Install `uv`: [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)
+
+
+### Install / Upgrade
+
+Install from PyPI (primary distribution channel):
+
+```bash
+uv tool install shellscripts
+```
+
+Upgrade to the latest published PyPI release:
+
+```bash
+s --upgrade
+```
+
+
+### Run Without Installing (uvx)
+
+```bash
+uvx shellscripts <command> [args...]
+```
+
+
+### Run From a Local Clone
+
+```bash
+./scripts/s.sh <command> [args...]
+```
+
+or
+
+```bash
+uv run --project . python -m shell_scripts <command> [args...]
+```
+
+
+## Install from GitHub (Alternative)
+
+PyPI is the primary distribution channel. As an alternative, the package can be installed from GitHub Releases, which also hosts intermediate and test releases that are not published on PyPI:
+
+```bash
+uv tool install shellscripts --force --from git+https://github.com/Ogekuri/shellScripts.git@vX.Y.Z
+```
+
+Intermediate and test releases are available at: [https://github.com/Ogekuri/shellScripts/releases](https://github.com/Ogekuri/shellScripts/releases).
+
+To upgrade to the newest tagged GitHub release, regardless of the branch that carries the tag, use the `--dev` (alias `--develop`) flag together with `--upgrade`:
+
+```bash
+s --upgrade --dev
+# or
+s --upgrade --develop
+```
+
+
+## Management Commands
+
+Global syntax:
+
+```bash
+shellscripts [command] [options]
+# or
+s [command] [options]
+```
+
+Built-in management flags:
+
+- `--help` : show full help or command help (`shellscripts --help <command>`).
+- `--version` / `--ver` : print the installed version plus the latest versions available on PyPI and GitHub.
+- `--upgrade` : run the configured upgrade command automatically on Linux (installs the latest PyPI release by default), otherwise print the manual command.
+- `--upgrade --dev` / `--upgrade --develop` : upgrade from the latest tagged GitHub release instead of PyPI, regardless of its source branch.
+- `--uninstall` : run configured uninstall command automatically on Linux, otherwise print the manual command.
+- `--write-config` : write the default runtime configuration file.
+
+### Runtime Configuration
+
+Generate a default config file:
+
+```bash
+s --write-config
+```
+
+Default location:
+
+```text
+~/.config/shellScripts/config.json
+```
+
+Top-level configuration keys:
+
+- `management`
+  - `upgrade`: command string executed by `--upgrade` (PyPI install by default).
+  - `upgrade_develop`: command template executed by `--upgrade --dev`; the `{tag}` placeholder is replaced with the latest GitHub release tag.
+  - `uninstall`: command string executed by `--uninstall`.
+- `dispatch`
+  - `diff`, `edit`, `view`: each command supports `categories` and `fallback` command vectors.
+- `req`
+  - `providers`: provider list forwarded to external `req`.
+  - `static_checks`: static-check entries forwarded to external `req`.
+
+
+## Shell Scripts
+
+### Command List
+
+| Command | Purpose |
+|---|---|
+| `ai-install` | Install AI CLIs (all or selected tools). |
+| `claude` | Launch Claude CLI in project context. |
+| `codex` | Launch Codex CLI in project context with auth sync and `CODEX_HOME`. |
+| `copilot` | Launch Copilot CLI in project context. |
+| `gemini` | Launch Gemini CLI in project context. |
+| `kiro` | Launch Kiro CLI in project context. |
+| `opencode` | Launch OpenCode CLI in project context. |
+| `pi` | Launch pi.dev CLI in project context (adds default `--tools` when missing). |
+| `clean` | Find and delete cache directories under the project root (or a passed directory). |
+| `req` | Run useReq bootstrap on current directory, first-level dirs, or recursively. |
+| `venv` | Recreate `.venv` and install `requirements.txt` if present. |
+| `tests` | Ensure/create `.venv` and run pytest (arguments passed through). |
+| `doxygen` | Generate HTML/XML/Markdown docs and optional PDF output. |
+| `vscode` | Open project in VS Code with `CODEX_HOME` set. |
+| `vsinsider` | Open project in VS Code Insiders with `CODEX_HOME` set. |
+| `diff` | Dispatch file differ by MIME/category. |
+| `edit` | Dispatch file editor by MIME/category. |
+| `view` | Dispatch file viewer by MIME/category. |
+| `pdf-crop` | Crop PDF pages with auto or manual bounding boxes. |
+| `pdf-merge` | Merge multiple PDFs preserving/rebuilding bookmarks. |
+| `pdf-split-by-format` | Split PDFs into parts when page format changes. |
+| `pdf-split-by-toc` | Split PDF into chapter files from level-1 TOC entries. |
+| `pdf-tiler-090` | Tile PDF to A4 at 90% scale. |
+| `pdf-tiler-100` | Tile PDF to A4 at original A1 size. |
+| `pdf-toc-clean` | Remove out-of-range TOC entries and write cleaned outputs. |
+| `dicom2jpg` | Convert DICOM images to JPEG (PixelMed). |
+| `dicomviewer` | Launch PixelMed DICOM viewer. |
+| `video2h264` | Convert one video to H.264 MP4 via ffmpeg. |
+| `video2h265` | Convert one video to H.265 MP4 via ffmpeg. |
+| `ubuntu-dark-theme` | Apply GNOME and Qt dark-theme settings. |
+
+### Selected Usage Examples
+
+Install all AI CLIs (default behavior):
+
+```bash
+s ai-install
+```
+
+Install only selected AI tools:
+
+```bash
+s ai-install --codex --gemini --claude
+```
+
+Run pi.dev with default tools injected automatically:
+
+```bash
+s pi
+```
+
+Override pi tools explicitly:
+
+```bash
+s pi --tools read,bash,grep,find
+```
+
+Run useReq bootstrap on first-level child directories:
+
+```bash
+s req --dirs
+```
+
+Clean caches without interactive confirmation:
+
+```bash
+s clean --yes
+```
+
+Crop PDF with automatic bbox over a page window:
+
+```bash
+s pdf-crop --in input.pdf --out cropped.pdf --analyze-pages 1-10 --pages 1-
+```
+
+Merge PDFs and choose output file:
+
+```bash
+s pdf-merge -o merged.pdf a.pdf b.pdf c.pdf
+```
+
+Split PDF by TOC chapters:
+
+```bash
+s pdf-split-by-toc document.pdf
+```
+
+Convert a video to H.264 MP4:
+
+```bash
+s video2h264 input.mov
+```
+
+Run tests and pass pytest options:
+
+```bash
+s tests -q -k "pdf"
+```
+
+Open current git project in VS Code / Insiders:
+
+```bash
+s vscode
+s vsinsider
+```
+
+
+## Acknowledgments

shellscripts-0.23.1.dist-info/RECORD

@@ -0,0 +1,45 @@
+shell_scripts/__init__.py,sha256=tcta0Vrn-w5n4wRkcb6xWB5jcyslWz3oKUyNDDU4ago,96
+shell_scripts/__main__.py,sha256=-wEmwKTfeY5TphAH82E38XRPoB4KT5QDLDgRZz84PTs,83
+shell_scripts/config.py,sha256=YUs8QWsZ31lJPrMpFqvn7YLQdseQnlaiu7OXcXsKdEw,12640
+shell_scripts/core.py,sha256=rhgy9xduzkujsjD4NRL2AYvtNI3yTVnPThzEAzyMWUM,11204
+shell_scripts/utils.py,sha256=bXSFRszGmkSKkxOUYJwqqVldveI9rrizkEu-nzstoJs,14133
+shell_scripts/version_check.py,sha256=GDE7IwCzt8-UJ0pFAOQzv0dIYUsynYRN1Z1Gz6Mx7Yo,13090
+shell_scripts/commands/__init__.py,sha256=tFiG-epwWLjfwnZ3LEXXULNk8bEquE5_x9uK59uamQo,3696
+shell_scripts/commands/_dc_common.py,sha256=kfUn92r6n8F1w27jy5QDJE_6Kvpvzhq6dUGNs0_GO0U,4695
+shell_scripts/commands/ai_install.py,sha256=BH38g3OXWQ4F60-pzTbt-fY67eFmRSOEzryhpxVSgQw,17011
+shell_scripts/commands/bin_links.py,sha256=7chuWbk1FdnxH9ak_fATdmUSOyzIbg4WmfRPCOw10-U,2425
+shell_scripts/commands/claude.py,sha256=_X76ygt0jnxZyyNoZ8qVhn6r2C0B9mcNIaKd_hLthl4,2049
+shell_scripts/commands/clean.py,sha256=LOK7bVzqpWDvFBMInlu9COtODVmjwOtwCHyMriq7wIk,2552
+shell_scripts/commands/codex.py,sha256=iHg5S_E8QpsGr2qQwucNDw-24-lcPH_FHsaGCxH9hEE,4331
+shell_scripts/commands/copilot.py,sha256=zYGbB33S8B8zWPi8jV-EBWSoxGv0-11K_zGgBkfi7-Y,1954
+shell_scripts/commands/dicom2jpg.py,sha256=YQQHdhwP8yi10UU3qWn4UzbCjSCK6C33bORcNWtXaek,2614
+shell_scripts/commands/dicomviewer.py,sha256=sMnwQGeHf7r8Qo0n8Cf_ZeTmcask3z5bqQZ44mvSMG8,2283
+shell_scripts/commands/diff_cmd.py,sha256=C6R4GiNhgvvlU6drCVCG9-TusLotNNcb9v5wBq10VJw,1828
+shell_scripts/commands/doxygen_cmd.py,sha256=wd4qecljYZ0lVpdu3D1qKf6cD9xNBv36TetfLlvdFJw,5111
+shell_scripts/commands/edit_cmd.py,sha256=WnWVs4Ojq0qN4fw9iqooUqQHK0XIfDUbJBRmI-AMrUE,1827
+shell_scripts/commands/gemini.py,sha256=efvOhfrDu6WkeJZ0WuRu_vp2fbqPkPrp9r6WECQJDxg,1902
+shell_scripts/commands/kiro.py,sha256=NuD2Zx76azDQAWbJ8YcewshEogLmrd-Avu9feisqHys,1871
+shell_scripts/commands/opencode.py,sha256=64I3IHrliAZ7C4jTU4WLxQcJHJohJcKex09yhegWUoc,1900
+shell_scripts/commands/pdf_crop.py,sha256=VliRAMHMjnSQK9mZhNoghftZAVGZeJG6xhrihcuuawQ,15135
+shell_scripts/commands/pdf_merge.py,sha256=vTTlUv8oVYUo9U45b4yUpK4x0unIwctgXV7g5exvihc,5996
+shell_scripts/commands/pdf_split_by_format.py,sha256=kWID9sadX9cf0jMWFqTyCFMRHwAFNZVmnp24IlcN1H8,7573
+shell_scripts/commands/pdf_split_by_toc.py,sha256=I027ldWXat8ODafn3KRD1X52yeUP2xez1PX-kFNptAg,6674
+shell_scripts/commands/pdf_tiler_090.py,sha256=1eLCw9rqGN8LELB5lBvx6xfaTYc4Kci5YDK2EvnHG6E,1781
+shell_scripts/commands/pdf_tiler_100.py,sha256=U-DlX_PJPHL2P2p0wvWMzb-XkxVYn5-Jb1vqlBzIAqA,1805
+shell_scripts/commands/pdf_toc_clean.py,sha256=7GroNjVbOoh184AbYoqXSVdK_RHqA3y5urjkZ4lcJbw,5907
+shell_scripts/commands/pi.py,sha256=Ozo-VKaieQYp1OFiyo2LFsxvpD-XYdO5JpcvTdqDEhQ,2381
+shell_scripts/commands/req_cmd.py,sha256=3zR4FRbZWebQa-csna7qWttVcZsLqAIqiJSjQ4Idtlk,13212
+shell_scripts/commands/tests_cmd.py,sha256=nKfD2sDb06Hy5J93yRH6dP4kSfV1sxLkpHHdTgqLvvw,2672
+shell_scripts/commands/ubuntu_dark_theme.py,sha256=O-Ku_U3ZwFNVBpSHYvsFZSK36SoDhrlFBeWlqD5_GYc,1987
+shell_scripts/commands/venv_cmd.py,sha256=X8phS-K4b0oOGuuwn2u84D1bcQlfo1QpJi1RI3VVe3s,2381
+shell_scripts/commands/video2h264.py,sha256=5Cj4OpDrl1Bm24wGBbzni2So1ELP3Wual3RaB98DQrs,2717
+shell_scripts/commands/video2h265.py,sha256=Sr_UWGz_V77x4anmuy8kiWZv5I_AOFlV0WDnJEToAhk,2675
+shell_scripts/commands/view_cmd.py,sha256=qHEivQHZpZCTE3VSFP1ay2SuqgancQlEKxJcKtyeqNA,1827
+shell_scripts/commands/vscode_cmd.py,sha256=Rkcjt5A1HMzqJoh2Yz9VRGoLP-L3qpRO5hkcSrzOmvA,1461
+shell_scripts/commands/vsinsider_cmd.py,sha256=KTTv1cVpJO-u1ktxOE0W_o4AAmz20pAvkDtyhpU9XBg,1548
+shellscripts-0.23.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+shellscripts-0.23.1.dist-info/METADATA,sha256=BihFSRKVrmcCCAiiJLu0B5seR0Unkn0W2-WCrrgWo0A,10985
+shellscripts-0.23.1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+shellscripts-0.23.1.dist-info/entry_points.txt,sha256=9ICAgH87fxHBzi3f6JXIVcsPWzAKsCh4_1xS8JThQ0M,85
+shellscripts-0.23.1.dist-info/top_level.txt,sha256=7bDVqjcR5CfCCArCP4X4e9gYJ-ua8z-GfQeHbAo8rCY,14
+shellscripts-0.23.1.dist-info/RECORD,,

shellscripts-0.23.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shellscripts-0.23.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+s = shell_scripts.core:main
+shellscripts = shell_scripts.core:main