localargo 0.1.0__py3-none-any.whl

localargo/utils/proc.py

@@ -0,0 +1,148 @@
+"""Safe subprocess helpers with timeouts and structured errors.
+
+All helpers avoid shell=True and return normalized outputs. Designed to be
+monkeypatch-friendly for tests and snapshotting.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+from localargo.logging import logger
+from localargo.utils.cli import check_cli_availability
+
+if TYPE_CHECKING:  # imported only for type checking
+    from collections.abc import Iterator
+
+
+class ProcessError(RuntimeError):
+    """Normalized process error with code/stdout/stderr attached."""
+
+    def __init__(self, message: str, *, code: int | None, stdout: str, stderr: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.stdout = stdout
+        self.stderr = stderr
+
+
+def _precheck_cli(cmd: list[str]) -> None:
+    if not cmd:
+        msg = "Empty command"
+        raise ValueError(msg)
+    cli_name = cmd[0]
+    # Validate common tools if referenced by name
+    if cli_name in ("kubectl", "argocd", "k3s", "kind", "docker"):
+        check_cli_availability(cli_name)
+
+
+def _fmt_cmd(cmd: list[str]) -> str:
+    return " ".join(cmd)
+
+
+def run(cmd: list[str], *, timeout: int = 120) -> str:
+    """Run a command and return stdout text.
+
+    Raises ProcessError on non-zero exit.
+    """
+    _precheck_cli(cmd)
+    logger.info("$ %s", _fmt_cmd(cmd))
+    try:
+        cp = subprocess.run(cmd, check=False, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired as e:
+        timeout_msg = f"Command timed out after {timeout}s: {' '.join(cmd)}"
+        raise ProcessError(
+            timeout_msg,
+            code=None,
+            stdout=str(e.stdout or ""),
+            stderr=str(e.stderr or ""),
+        ) from e
+
+    if cp.returncode != 0:
+        _log_failure(cp, cmd)
+        failure_msg = (
+            "Command failed"
+            f" (exit={cp.returncode})\n"
+            f"cmd: {_fmt_cmd(cmd)}\n"
+            f"stdout:\n{(cp.stdout or '').strip()}\n"
+            f"stderr:\n{(cp.stderr or '').strip()}"
+        )
+        raise ProcessError(
+            failure_msg,
+            code=cp.returncode,
+            stdout=str(cp.stdout),
+            stderr=str(cp.stderr),
+        )
+    return cp.stdout
+
+
+def run_json(cmd: list[str], *, timeout: int = 120) -> Any:
+    """Run a command and parse stdout as JSON."""
+    logger.info("$ %s", _fmt_cmd(cmd))
+    out = run(cmd, timeout=timeout)
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as e:
+        decode_msg = "Invalid JSON output"
+        raise ProcessError(decode_msg, code=0, stdout=out, stderr=str(e)) from e
+
+
+def run_stream(cmd: list[str], *, bufsize: int = 1) -> Iterator[str]:
+    """Run a command and yield stdout lines as they arrive.
+
+    Caller must consume iterator; termination closes process. Any non-zero exit
+    will raise ProcessError at the end (after stream drains) with captured stderr.
+    """
+    _precheck_cli(cmd)
+    logger.info("$ %s", _fmt_cmd(cmd))
+    proc = _popen_with_pipes(cmd, bufsize)
+    stdout_iter = _get_stdout_iterator(proc)
+    try:
+        for line in stdout_iter:
+            yield line.rstrip("\n")
+    finally:
+        rc, stdout_data, stderr_data = _finalize_process(proc)
+        _raise_on_nonzero_rc(rc, stdout_data, stderr_data)
+
+
+def _popen_with_pipes(cmd: list[str], bufsize: int) -> subprocess.Popen[str]:
+    return subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=bufsize,
+    )
+
+
+def _get_stdout_iterator(proc: subprocess.Popen[str]) -> Iterator[str]:
+    if proc.stdout is None:
+        proc.kill()
+        no_stdout_msg = "No stdout from process"
+        raise ProcessError(no_stdout_msg, code=None, stdout="", stderr="")
+    return proc.stdout
+
+
+def _raise_on_nonzero_rc(rc: int | None, stdout_data: str, stderr_data: str) -> None:
+    if rc not in (0, None):
+        rc_msg = f"Command failed with exit code {rc}"
+        raise ProcessError(rc_msg, code=rc, stdout=stdout_data or "", stderr=stderr_data or "")
+
+
+def _log_failure(cp: subprocess.CompletedProcess[str], cmd: list[str]) -> None:
+    logger.debug("Command failed (%s): %s", cp.returncode, " ".join(cmd))
+    if cp.stdout:
+        logger.debug("Stdout: %s", cp.stdout)
+    if cp.stderr:
+        logger.debug("Stderr: %s", cp.stderr)
+
+
+def _finalize_process(proc: subprocess.Popen[str]) -> tuple[int | None, str, str]:
+    stdout_data = ""
+    stderr_data = ""
+    try:
+        stdout_data, stderr_data = proc.communicate(timeout=5)
+    except (subprocess.TimeoutExpired, OSError):
+        proc.kill()
+    return proc.returncode, stdout_data, stderr_data

localargo/utils/retry.py

@@ -0,0 +1,58 @@
+"""Minimal retry/backoff utilities for transient failures."""
+
+from __future__ import annotations
+
+import random
+import time
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:  # imported only for type checking
+    from collections.abc import Callable
+
+T = TypeVar("T")
+
+
+# pylint: disable=too-many-arguments
+def retry(
+    func: Callable[[], T],
+    *,
+    attempts: int = 3,
+    base_delay: float = 0.5,
+    max_delay: float = 5.0,
+    jitter: float = 0.1,
+    retry_on: tuple[type[Exception], ...] = (Exception,),
+) -> T:  # pylint: disable=too-many-arguments
+    """Retry a zero-arg callable with exponential backoff and jitter.
+
+    Args:
+        func (Callable[[], T]): Callable with no arguments to execute.
+        attempts (int): Total attempts including the first try.
+        base_delay (float): Initial delay in seconds.
+        max_delay (float): Maximum delay cap in seconds.
+        jitter (float): Proportional jitter to add/subtract from delay.
+        retry_on (tuple[type[Exception], ...]): Exception types to retry on.
+
+    Returns:
+        T: The return value from ``func`` when it succeeds.
+
+    Raises:
+        RuntimeError: If attempts are exhausted; wraps the last exception if present.
+    """
+    last_exc: BaseException | None = None
+    for i in range(attempts):
+        try:
+            return func()
+        except retry_on as e:
+            last_exc = e
+            if i == attempts - 1:
+                break
+            delay = min(max_delay, base_delay * (2**i))
+            jitter_amt = delay * jitter
+            # Use random.random(); suppress security lint as this is non-crypto usage
+            time.sleep(max(0.0, delay + (random.random() * 2 - 1) * jitter_amt))  # noqa: S311
+    if last_exc is None:
+        msg = "retry: exhausted attempts without result"
+        raise RuntimeError(msg)
+    # Wrap the final exception to provide a consistent, documented exception type
+    final_msg = f"retry: failed after {attempts} attempts"
+    raise RuntimeError(final_msg) from last_exc

localargo-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: localargo
+Version: 0.1.0
+Project-URL: Documentation, https://github.com/williamkborn/localargo#readme
+Project-URL: Issues, https://github.com/williamkborn/localargo/issues
+Project-URL: Source, https://github.com/williamkborn/localargo
+Author-email: William Born <william.born.git@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: click
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Requires-Dist: rich-click
+Provides-Extra: dev
+Requires-Dist: lizard; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pydoclint; extra == 'dev'
+Requires-Dist: pylint; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: watch
+Requires-Dist: watchdog>=2.0.0; extra == 'watch'
+Description-Content-Type: text/markdown
+
+# localargo
+
+[![PyPI - Version](https://img.shields.io/pypi/v/localargo.svg)](https://pypi.org/project/localargo)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/localargo.svg)](https://pypi.org/project/localargo)
+
+**Convenient ArgoCD local development tool**
+
+Localargo is a command-line tool that makes ArgoCD development workflows faster and more convenient. It provides streamlined commands for managing local clusters, applications, secrets, port forwarding, and debugging - all designed specifically for ArgoCD development.
+
+## Features
+
+- 🚀 **Cluster Management**: Set up and switch between local/remote Kubernetes clusters
+- 📦 **Application Management**: Create, sync, and manage ArgoCD applications
+- 🌐 **Port Forwarding**: Easily access services running in your applications
+- 🔐 **Secrets Management**: Create and manage secrets for local development
+- 🔄 **Sync Operations**: Sync applications with watch mode for continuous development
+- 📋 **Templates**: Quick-start applications from common templates
+- 🔍 **Debug Tools**: Comprehensive debugging and troubleshooting utilities
+
+## Quick Start
+
+```bash
+# Install localargo
+pip install localargo
+
+# Initialize a local cluster with ArgoCD (uses KinD by default)
+localargo cluster init
+
+# Create an application from a template
+localargo template create my-app --repo https://github.com/myorg/myrepo
+
+# Port forward services for easy access
+localargo port-forward start my-service
+
+# Sync and watch for changes
+localargo sync my-app --watch
+```
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Documentation](#documentation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install localargo
+```
+
+### Development Setup
+
+For contributors and development, we recommend using [Mise](https://mise.jdx.dev/) to set up the complete development environment:
+
+```bash
+# Install Mise (macOS with Homebrew)
+brew install mise
+
+# Install all development tools
+mise install
+
+# Create Hatch environment
+hatch env create
+
+# All tools will be automatically available
+```
+
+### 🧩 Git Hook Setup
+
+To ensure code quality before every commit, enable the mise-managed pre-commit hook:
+
+```bash
+mise generate git-pre-commit --write --task=precommit
+```
+
+This creates `.git/hooks/pre-commit`, which automatically runs:
+
+- `hatch fmt`
+- `hatch run typecheck`
+- `hatch run test`
+
+If any step fails, the commit will be blocked until fixed.
+
+You can also run it manually at any time:
+
+```bash
+mise run precommit
+```
+
+### Optional Dependencies
+
+For file watching functionality:
+```console
+pip install localargo[watch]
+```
+
+## Documentation
+
+📖 Full documentation is available at [docs/](docs/) and can be built locally using mdBook.
+
+To build the documentation:
+
+```console
+# Install mdBook (if not already installed)
+cargo install mdbook
+
+# Build the docs
+cd docs && mdbook build
+
+# Or using Hatch
+hatch run docs:build
+```
+
+## License
+
+`localargo` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
+# Test comment for precommit hook

localargo-0.1.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+localargo/__about__.py,sha256=fW2ZWJXDc2m1H_7gmps8zUY8ymGIxOYh4pTbtCpqgDo,178
+localargo/__init__.py,sha256=QE27YHqsJxPS736Rm6krKpVd2qus4RVY3X7WA1ZFVFc,210
+localargo/__main__.py,sha256=9AEtbYXWFUkbdk5Pql_fE0hEc1SoUbREbCZwkwIJok4,276
+localargo/logging.py,sha256=_u0773v4ts0p9QEt8v0LNWeVi4XYgEhNlvcqCT9W9O8,2632
+localargo/manager.py,sha256=3n1LVHAzswPM9U7KBSSWkG32MDUqLxYRvsnDxOfYqUc,8487
+localargo/cli/__init__.py,sha256=n8KEjDrlxQC7n3uJJsOWI_gN0CcWqTqL8kgfquyZbhI,1817
+localargo/cli/commands/__init__.py,sha256=Jg__qmv9D1fEPtuAVFSpqlJIFyzU09-JspJRTnv_p0Y,143
+localargo/cli/commands/app.py,sha256=wWzooXxFiSbaOzKEv-hH39TszjX5dl77zJZpOgpLt7A,4739
+localargo/cli/commands/cluster.py,sha256=oy1tiHNuiq9PKCSaOHKBOJXVLg_3gYAgfGb88PwrII8,10332
+localargo/cli/commands/debug.py,sha256=iVC0olbJ-SDd-h9CS_tEvOOyH-BGW1aQFpNOwuGAQsA,16044
+localargo/cli/commands/port_forward.py,sha256=m4tf1EjPgUvdgscbKuKfRfRNBrQtEQDtuzkZo_ZH_Do,9700
+localargo/cli/commands/secrets.py,sha256=2SWgLQE8bs_hq9t_fDsWBIIHu0J2OueitE4M2IyEOf4,9836
+localargo/cli/commands/sync.py,sha256=11mFlUcUKVK7ye4B1mgEdyP2fBZeGcStDLkjJhODkTs,9423
+localargo/cli/commands/template.py,sha256=YVM-imNCVduD5sLXbDq-6dsT4CxwNJK_Da7qJ70exAw,9336
+localargo/cli/commands/up.py,sha256=s3uyFRGf7VG4yJDLg6JWV1Wn88wiwZZwQSRDOvaLXhc,12065
+localargo/config/__init__.py,sha256=w0VhemJyCQWTsLws4qLgQX6LH_KI_Ptl0IBa-aw2GTg,353
+localargo/config/manifest.py,sha256=K00_PzSmCdfZ6WDoGHakhZA10aGD3u1DG9NS59rlJuE,16613
+localargo/config/store.py,sha256=tJkjnf3O_Y47ieGq1HrsILcjH8DCUKwr2ZIv5YohvgU,2101
+localargo/core/__init__.py,sha256=9n9yPqdXZCPhp5qxKNNgmqU_ei6p_Sk-rJ0jwZm67B8,209
+localargo/core/apps.py,sha256=zrM3N8-QRidgP5lyDISCPCkjYtYIxTH_CetjFniuoj8,10688
+localargo/core/argocd.py,sha256=KAUf4ZbEjbH-If65mpTCmxJuPf-I7g51ZjsIwOIIr5Q,16858
+localargo/core/catalog.py,sha256=qYb35jOQrdfutqL54_wln7HB-blK5ZCmbpN376upXe8,9514
+localargo/core/cluster.py,sha256=GVUjct0ABK1SjdKJ4WLhbkHoETb32s2oZAOnp-msXgQ,5449
+localargo/core/k8s.py,sha256=iR69SsZ8eo3kqg9f2VlVcNAVXTUJ6Uub1xv1QLdUep0,4649
+localargo/eyecandy/__init__.py,sha256=lGECUAV_3tAH0MD5dHJolaxHe7XFvzNJhgtEfxgSd3w,469
+localargo/eyecandy/progress_steps.py,sha256=FQoxuzm683PXHrDi-ssLICsMYH6VWXiyAiBNscdV-_Y,9674
+localargo/eyecandy/table_renderer.py,sha256=jdWOb8tnHNAFN1WjQeaEBMy1GaO03tmEE1cB-g3Cz1I,5101
+localargo/eyecandy/tables.py,sha256=I4yKYeF5lEy4dAUdNIAFmpZUh-mfNgvAdAgq7aZbYik,1859
+localargo/providers/__init__.py,sha256=E43_1oDYfZEztpXgfbjFf2cBthBzlqYGrHBJZXO-Y4k,190
+localargo/providers/base.py,sha256=bChlPu78D9FK0sx090Yf2DGUUjv3x-GSis7o2I8vanU,4914
+localargo/providers/k3s.py,sha256=RFA-e3N1dgKaLLZPA99QytDv-jBwT1unrwPADl1Kz60,7033
+localargo/providers/kind.py,sha256=yACX1d8rgwcf-nl9GcBNu0dBtrpqoH2HEJPT76ZaFFY,11696
+localargo/providers/registry.py,sha256=4a3mv2mAHE9sLrV6EEPvJNmRnSrvxoLXt35gQOTuuTw,1271
+localargo/utils/__init__.py,sha256=PmDWmjpw4k45fgkXDouw6D3VxzpzNePnKoi9Fv2HQwQ,151
+localargo/utils/cli.py,sha256=NgWhY101VBIAAOjvkrrxqzmUVRgXUqGWCxYp4bW-T1Y,6623
+localargo/utils/proc.py,sha256=wYnX0qL0JB_75z9XQ2BP_dzZf7g0yP9yR9ng5weAluI,4704
+localargo/utils/retry.py,sha256=tavt_dwJcCOzKiDGlo8PnEiunVmEq3mss9wRtgfT07A,2032
+localargo-0.1.0.dist-info/METADATA,sha256=zC9xfypcB1padk5kIc9znIwe7CCzyYaxaOfTz7XS7zI,4282
+localargo-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+localargo-0.1.0.dist-info/entry_points.txt,sha256=d6B-IhXUjU1Pzeyu6j9JEzx2BwKnnuO1szfxMhFZHSc,54
+localargo-0.1.0.dist-info/licenses/LICENSE,sha256=lsN04Uixq6Di7nTLgytuiF3fPI7w2iykwSrqH9Px2UI,1069
+localargo-0.1.0.dist-info/RECORD,,

localargo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

localargo-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+localargo = localargo.cli:localargo

localargo-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 williamkborn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.