salla-gitpuller 1.0.2__tar.gz → 1.1.0__tar.gz

salla_gitpuller-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mohammed Junaid, Muhammad Zahid
+
+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.

salla_gitpuller-1.1.0/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: salla_gitpuller
+Version: 1.1.0
+Summary: A lightweight utility to git pull a repository using SSH deploy keys stored in environment variables
+Author-email: Mohammed Junaid <safijunaid.ss@gmail.com>, Muhammad Zahid <zahidmuhammad127@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Zahid07/gitpuller
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.20
+Dynamic: license-file
+
+# gitpuller
+
+A lightweight utility to keep a git repository in sync with its remote, designed
+to run **inside Mage AI pipelines** as an auto-pull step. It authenticates with an
+SSH deploy key stored in an environment variable, forces the local checkout to
+match the remote branch (even if someone manually edited files on the runner),
+and sends a de-duplicated Slack alert if anything goes wrong.
+
+---
+
+## Why this exists
+
+Mage runners are long-lived boxes. If anyone manually edits a tracked file,
+adds a stray file, or commits locally, a plain `git pull` fails with an opaque
+error like:
+
+```
+Command '['git', '-c', 'core.sshCommand=...', 'pull', 'git@github.com:...', 'master']'
+returned non-zero exit status 1.
+```
+
+gitpuller solves three problems at once:
+
+1. **Clear errors** — surfaces the actual git output, not the wrapper message.
+2. **Self-healing sync** — discards local drift so the pull can't be blocked.
+3. **Alerting without spam** — pings Slack on failure, but suppresses repeats of
+   the same error within a configurable window.
+
+---
+
+## Installation
+
+```bash
+pip install salla_gitpuller
+```
+
+Dependency: [`requests`](https://pypi.org/project/requests/) (installed
+automatically). Optional: `mage-ai` — only needed if you want alert-suppression
+state to persist across pipeline runs (see [State management](#state-management)).
+
+---
+
+## Quick start
+
+```python
+from gitpuller import GitPullExecutor
+
+executor = GitPullExecutor(
+    slack_webhook_url="https://hooks.slack.com/services/XXX",  # or set CDM_SLACK_WEBHOOK_URL
+    use_mage_ai=True,                                          # persist alert state via Mage
+)
+
+result = executor.execute_with_alerting(
+    repo_path="/home/src/my-repo",
+    git_url="git@github.com:my-org/my-repo.git",
+    workspace_name="myworkspace",   # reads the private key from {workspace_name}_SSHKEY
+    # branch omitted -> defaults to "master"
+)
+
+print(result["git_pull_status"])     # "success"
+print(result["discarded_changes"])   # what local drift (if any) was wiped
+```
+
+On failure, `execute_with_alerting` sends a Slack alert (subject to suppression)
+and then **re-raises**, so the Mage pipeline still fails loudly.
+
+---
+
+## How it works
+
+`execute_git_pull` does **not** run `git pull`. Instead it forces the local repo
+to exactly match the remote, which is robust against manual edits *and* divergent
+history (local commits / rewritten history) that a stash-based approach can't
+handle:
+
+1. **Prepare the SSH key** — the private deploy key is read from an env var,
+   normalized (strips wrapping quotes, converts literal `\n` to real newlines,
+   ensures a trailing newline), and written to `~/.ssh` with strict `0600`
+   permissions. It is injected per-command via
+   `git -c core.sshCommand="ssh -i <key> -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`.
+2. **`git fetch <url> <branch>`** — `FETCH_HEAD` now points at the remote tip.
+3. **Snapshot + log local drift** — before anything is discarded, it records:
+   - **working tree changes** — uncommitted edits and untracked files
+     (`git status --porcelain`),
+   - **local-only commits** — commits on the runner but not the remote
+     (`FETCH_HEAD..HEAD`),
+   and prints them to the pipeline log so you have a record of what was wiped.
+4. **`git reset --hard FETCH_HEAD`** — makes the working tree and branch pointer
+   match the remote exactly.
+5. **`git clean -fd`** — removes untracked files/directories so the tree truly
+   matches remote. **Ignored files are preserved** (no `-x`), so runner-local
+   `.env` files and deploy keys survive.
+6. **Cleanup** — the key file is removed and the working directory is restored,
+   even on failure (`finally`).
+
+Any failing step raises a `RuntimeError` containing the **real git stdout/stderr
+and exit code**, which becomes the Slack alert body and the pipeline error.
+
+> ⚠️ **This is destructive by design.** Local changes on the runner are treated as
+> contamination and discarded. Don't point gitpuller at a repo where the runner
+> holds work you intend to keep.
+
+---
+
+## API
+
+### `GitPullExecutor(slack_webhook_url=None, use_mage_ai=False, state_manager=None)`
+
+| Param | Description |
+|-------|-------------|
+| `slack_webhook_url` | Slack incoming-webhook URL. Falls back to the `CDM_SLACK_WEBHOOK_URL` env var. Required (one of the two must be set). |
+| `use_mage_ai` | If `True`, persist alert-suppression state via Mage global variables (falls back to in-memory if Mage isn't installed). |
+| `state_manager` | Inject a custom `StateManager`; overrides `use_mage_ai`. |
+
+### `execute_with_alerting(...)` → `dict`
+
+Runs the sync and, on failure, alerts Slack (with suppression) then re-raises.
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `repo_path` | — | Absolute path to the local repo (must exist). |
+| `git_url` | — | SSH remote URL, e.g. `git@github.com:Org/repo.git`. |
+| `branch` | `"master"` | Branch to sync to. **Note: defaults to `master`, not `main`.** |
+| `ssh_key` | `None` | Private key material. If omitted, read from `{workspace_name}_SSHKEY`. |
+| `workspace_name` | `None` | Used to locate the key env var and name the key file. |
+| `pipeline_uuid` | `"auto_git_pull"` | Key under which alert state is stored. |
+| `suppression_hours` | `1` | Don't re-alert on the *same* error within this many hours. |
+| `key_filename` | `None` | Override the on-disk key filename. |
+| `ssh_dir` | `"/home/src/.ssh"` | Directory to write the key into. |
+
+### `execute_git_pull(...)` → `dict`
+
+Same signature as above (minus `pipeline_uuid` / `suppression_hours`). Performs
+the sync **without** alerting — use this if you handle errors yourself.
+
+### Return value
+
+```python
+{
+    "workspace": "myworkspace",
+    "repo_path": "/home/src/my-repo",
+    "git_pull_status": "success",          # or raises on error
+    "git_pull_output": "HEAD is now at <sha> <subject>",
+    "discarded_changes": {
+        "working_tree_changes": "?? stray.txt",      # git status --porcelain output
+        "local_commits": "949688e local-only commit" # FETCH_HEAD..HEAD output
+    },
+    "key_env_var_used": "myworkspace_SSHKEY",
+}
+```
+
+---
+
+## SSH key setup
+
+Provide the **private** deploy key as an environment variable named
+`{workspace_name}_SSHKEY` (e.g. `myworkspace_SSHKEY`), or pass `ssh_key=` directly.
+The matching public key must be registered as a deploy key on the GitHub repo.
+
+The key may be stored with literal `\n` (single-line) or real newlines — both are
+handled. Wrapping quotes are stripped automatically.
+
+### Use a read-only deploy key
+
+gitpuller is a one-way mirror (remote → runner) and **never pushes**. Its only
+remote operation is `git fetch`; the reset and clean steps are local. So the
+deploy key only needs **read access** — leave GitHub's *"Allow write access"*
+checkbox **unchecked**. This is the least-privilege setup and means the runner
+can never push its discarded local changes back upstream.
+
+Setup steps:
+
+1. Generate a dedicated key pair: `ssh-keygen -t ed25519 -f deploy_key -N ""`.
+2. On the GitHub repo: **Settings → Deploy keys → Add deploy key**, paste
+   `deploy_key.pub`, and leave **Allow write access unchecked**.
+3. Store the **private** key (`deploy_key`) in the `{workspace_name}_SSHKEY` env var.
+
+**Note:** GitHub deploy keys are **per-repository** — each repo you sync needs its
+own key pair and its own `{workspace_name}_SSHKEY` env var.
+
+On first connection the remote host key is auto-accepted
+(`StrictHostKeyChecking=accept-new`), i.e. trust-on-first-use rather than a
+pre-pinned fingerprint.
+
+---
+
+## State management
+
+Alert suppression needs to remember the last error and when it was alerted:
+
+- **`InMemoryStateManager`** (default) — process-local; suppression only works
+  within a single run.
+- **`MageAIStateManager`** (`use_mage_ai=True`) — persists across runs via Mage
+  global variables, so repeated failures across scheduled runs stay de-duplicated.
+- **`StateManager`** — subclass it to plug in your own backend (e.g. Redis, a DB).
+
+---
+
+## Build & release
+
+```bash
+rm -rf build dist *.egg-info
+python -m build
+# then upload to PyPI (twine upload dist/*) and bump the version in pyproject.toml
+```
+
+Keep the version in sync in **both** `pyproject.toml` and `gitpuller/__init__.py`.
+
+---
+
+## Changelog
+
+### 1.1.0 (current)
+
+Reliability and clarity overhaul.
+
+- **Self-healing sync.** Replaced `git pull` with `git fetch` →
+  `git reset --hard FETCH_HEAD` → `git clean -fd`. Manual edits, stray files, and
+  even local commits / divergent history on the runner no longer break the sync.
+  Ignored files (`.env`, keys) are preserved.
+- **Clear error messages.** Failures now raise with the real git stdout/stderr and
+  exit code instead of the opaque
+  `Command '[...]' returned non-zero exit status 1.` wrapper. The same detail flows
+  into the Slack alert.
+- **Audit log of discarded changes.** Before resetting, the working-tree drift and
+  any local-only commits are logged and returned under `discarded_changes`, so
+  there's always a record of what was wiped.
+- **Packaging fixes.** Declared the previously-missing `requests` dependency; synced
+  the version between `pyproject.toml` and `__init__.py`.
+- **Docs & comments.** Full README and inline documentation across all modules.
+
+> **Migration note:** `git_pull_output` now reflects `reset --hard` output
+> (`HEAD is now at <sha> <subject>`) rather than pull's `Updating x..y` /
+> `Already up to date`. The result key `recovery_steps` (briefly present during
+> development) is replaced by `discarded_changes`. Update any code that parses
+> these. The public method signatures are unchanged.
+
+### 1.0.x (previous)
+
+- Initial release. Ran a plain `git pull <url> <branch>` over an SSH deploy key.
+- Slack alerting with same-error suppression (`AlertManager` + `StateManager`,
+  in-memory or Mage-backed).
+- **Limitations addressed in 1.1.0:** any manual change on the runner caused the
+  pull to fail; errors were opaque wrapper messages; `requests` was imported but
+  not declared as a dependency.
+
+---
+
+<sub>Created and maintained by Mohammed Junaid and Muhammad Zahid.</sub>

salla_gitpuller-1.1.0/README.md

@@ -0,0 +1,249 @@
+# gitpuller
+
+A lightweight utility to keep a git repository in sync with its remote, designed
+to run **inside Mage AI pipelines** as an auto-pull step. It authenticates with an
+SSH deploy key stored in an environment variable, forces the local checkout to
+match the remote branch (even if someone manually edited files on the runner),
+and sends a de-duplicated Slack alert if anything goes wrong.
+
+---
+
+## Why this exists
+
+Mage runners are long-lived boxes. If anyone manually edits a tracked file,
+adds a stray file, or commits locally, a plain `git pull` fails with an opaque
+error like:
+
+```
+Command '['git', '-c', 'core.sshCommand=...', 'pull', 'git@github.com:...', 'master']'
+returned non-zero exit status 1.
+```
+
+gitpuller solves three problems at once:
+
+1. **Clear errors** — surfaces the actual git output, not the wrapper message.
+2. **Self-healing sync** — discards local drift so the pull can't be blocked.
+3. **Alerting without spam** — pings Slack on failure, but suppresses repeats of
+   the same error within a configurable window.
+
+---
+
+## Installation
+
+```bash
+pip install salla_gitpuller
+```
+
+Dependency: [`requests`](https://pypi.org/project/requests/) (installed
+automatically). Optional: `mage-ai` — only needed if you want alert-suppression
+state to persist across pipeline runs (see [State management](#state-management)).
+
+---
+
+## Quick start
+
+```python
+from gitpuller import GitPullExecutor
+
+executor = GitPullExecutor(
+    slack_webhook_url="https://hooks.slack.com/services/XXX",  # or set CDM_SLACK_WEBHOOK_URL
+    use_mage_ai=True,                                          # persist alert state via Mage
+)
+
+result = executor.execute_with_alerting(
+    repo_path="/home/src/my-repo",
+    git_url="git@github.com:my-org/my-repo.git",
+    workspace_name="myworkspace",   # reads the private key from {workspace_name}_SSHKEY
+    # branch omitted -> defaults to "master"
+)
+
+print(result["git_pull_status"])     # "success"
+print(result["discarded_changes"])   # what local drift (if any) was wiped
+```
+
+On failure, `execute_with_alerting` sends a Slack alert (subject to suppression)
+and then **re-raises**, so the Mage pipeline still fails loudly.
+
+---
+
+## How it works
+
+`execute_git_pull` does **not** run `git pull`. Instead it forces the local repo
+to exactly match the remote, which is robust against manual edits *and* divergent
+history (local commits / rewritten history) that a stash-based approach can't
+handle:
+
+1. **Prepare the SSH key** — the private deploy key is read from an env var,
+   normalized (strips wrapping quotes, converts literal `\n` to real newlines,
+   ensures a trailing newline), and written to `~/.ssh` with strict `0600`
+   permissions. It is injected per-command via
+   `git -c core.sshCommand="ssh -i <key> -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new"`.
+2. **`git fetch <url> <branch>`** — `FETCH_HEAD` now points at the remote tip.
+3. **Snapshot + log local drift** — before anything is discarded, it records:
+   - **working tree changes** — uncommitted edits and untracked files
+     (`git status --porcelain`),
+   - **local-only commits** — commits on the runner but not the remote
+     (`FETCH_HEAD..HEAD`),
+   and prints them to the pipeline log so you have a record of what was wiped.
+4. **`git reset --hard FETCH_HEAD`** — makes the working tree and branch pointer
+   match the remote exactly.
+5. **`git clean -fd`** — removes untracked files/directories so the tree truly
+   matches remote. **Ignored files are preserved** (no `-x`), so runner-local
+   `.env` files and deploy keys survive.
+6. **Cleanup** — the key file is removed and the working directory is restored,
+   even on failure (`finally`).
+
+Any failing step raises a `RuntimeError` containing the **real git stdout/stderr
+and exit code**, which becomes the Slack alert body and the pipeline error.
+
+> ⚠️ **This is destructive by design.** Local changes on the runner are treated as
+> contamination and discarded. Don't point gitpuller at a repo where the runner
+> holds work you intend to keep.
+
+---
+
+## API
+
+### `GitPullExecutor(slack_webhook_url=None, use_mage_ai=False, state_manager=None)`
+
+| Param | Description |
+|-------|-------------|
+| `slack_webhook_url` | Slack incoming-webhook URL. Falls back to the `CDM_SLACK_WEBHOOK_URL` env var. Required (one of the two must be set). |
+| `use_mage_ai` | If `True`, persist alert-suppression state via Mage global variables (falls back to in-memory if Mage isn't installed). |
+| `state_manager` | Inject a custom `StateManager`; overrides `use_mage_ai`. |
+
+### `execute_with_alerting(...)` → `dict`
+
+Runs the sync and, on failure, alerts Slack (with suppression) then re-raises.
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `repo_path` | — | Absolute path to the local repo (must exist). |
+| `git_url` | — | SSH remote URL, e.g. `git@github.com:Org/repo.git`. |
+| `branch` | `"master"` | Branch to sync to. **Note: defaults to `master`, not `main`.** |
+| `ssh_key` | `None` | Private key material. If omitted, read from `{workspace_name}_SSHKEY`. |
+| `workspace_name` | `None` | Used to locate the key env var and name the key file. |
+| `pipeline_uuid` | `"auto_git_pull"` | Key under which alert state is stored. |
+| `suppression_hours` | `1` | Don't re-alert on the *same* error within this many hours. |
+| `key_filename` | `None` | Override the on-disk key filename. |
+| `ssh_dir` | `"/home/src/.ssh"` | Directory to write the key into. |
+
+### `execute_git_pull(...)` → `dict`
+
+Same signature as above (minus `pipeline_uuid` / `suppression_hours`). Performs
+the sync **without** alerting — use this if you handle errors yourself.
+
+### Return value
+
+```python
+{
+    "workspace": "myworkspace",
+    "repo_path": "/home/src/my-repo",
+    "git_pull_status": "success",          # or raises on error
+    "git_pull_output": "HEAD is now at <sha> <subject>",
+    "discarded_changes": {
+        "working_tree_changes": "?? stray.txt",      # git status --porcelain output
+        "local_commits": "949688e local-only commit" # FETCH_HEAD..HEAD output
+    },
+    "key_env_var_used": "myworkspace_SSHKEY",
+}
+```
+
+---
+
+## SSH key setup
+
+Provide the **private** deploy key as an environment variable named
+`{workspace_name}_SSHKEY` (e.g. `myworkspace_SSHKEY`), or pass `ssh_key=` directly.
+The matching public key must be registered as a deploy key on the GitHub repo.
+
+The key may be stored with literal `\n` (single-line) or real newlines — both are
+handled. Wrapping quotes are stripped automatically.
+
+### Use a read-only deploy key
+
+gitpuller is a one-way mirror (remote → runner) and **never pushes**. Its only
+remote operation is `git fetch`; the reset and clean steps are local. So the
+deploy key only needs **read access** — leave GitHub's *"Allow write access"*
+checkbox **unchecked**. This is the least-privilege setup and means the runner
+can never push its discarded local changes back upstream.
+
+Setup steps:
+
+1. Generate a dedicated key pair: `ssh-keygen -t ed25519 -f deploy_key -N ""`.
+2. On the GitHub repo: **Settings → Deploy keys → Add deploy key**, paste
+   `deploy_key.pub`, and leave **Allow write access unchecked**.
+3. Store the **private** key (`deploy_key`) in the `{workspace_name}_SSHKEY` env var.
+
+**Note:** GitHub deploy keys are **per-repository** — each repo you sync needs its
+own key pair and its own `{workspace_name}_SSHKEY` env var.
+
+On first connection the remote host key is auto-accepted
+(`StrictHostKeyChecking=accept-new`), i.e. trust-on-first-use rather than a
+pre-pinned fingerprint.
+
+---
+
+## State management
+
+Alert suppression needs to remember the last error and when it was alerted:
+
+- **`InMemoryStateManager`** (default) — process-local; suppression only works
+  within a single run.
+- **`MageAIStateManager`** (`use_mage_ai=True`) — persists across runs via Mage
+  global variables, so repeated failures across scheduled runs stay de-duplicated.
+- **`StateManager`** — subclass it to plug in your own backend (e.g. Redis, a DB).
+
+---
+
+## Build & release
+
+```bash
+rm -rf build dist *.egg-info
+python -m build
+# then upload to PyPI (twine upload dist/*) and bump the version in pyproject.toml
+```
+
+Keep the version in sync in **both** `pyproject.toml` and `gitpuller/__init__.py`.
+
+---
+
+## Changelog
+
+### 1.1.0 (current)
+
+Reliability and clarity overhaul.
+
+- **Self-healing sync.** Replaced `git pull` with `git fetch` →
+  `git reset --hard FETCH_HEAD` → `git clean -fd`. Manual edits, stray files, and
+  even local commits / divergent history on the runner no longer break the sync.
+  Ignored files (`.env`, keys) are preserved.
+- **Clear error messages.** Failures now raise with the real git stdout/stderr and
+  exit code instead of the opaque
+  `Command '[...]' returned non-zero exit status 1.` wrapper. The same detail flows
+  into the Slack alert.
+- **Audit log of discarded changes.** Before resetting, the working-tree drift and
+  any local-only commits are logged and returned under `discarded_changes`, so
+  there's always a record of what was wiped.
+- **Packaging fixes.** Declared the previously-missing `requests` dependency; synced
+  the version between `pyproject.toml` and `__init__.py`.
+- **Docs & comments.** Full README and inline documentation across all modules.
+
+> **Migration note:** `git_pull_output` now reflects `reset --hard` output
+> (`HEAD is now at <sha> <subject>`) rather than pull's `Updating x..y` /
+> `Already up to date`. The result key `recovery_steps` (briefly present during
+> development) is replaced by `discarded_changes`. Update any code that parses
+> these. The public method signatures are unchanged.
+
+### 1.0.x (previous)
+
+- Initial release. Ran a plain `git pull <url> <branch>` over an SSH deploy key.
+- Slack alerting with same-error suppression (`AlertManager` + `StateManager`,
+  in-memory or Mage-backed).
+- **Limitations addressed in 1.1.0:** any manual change on the runner caused the
+  pull to fail; errors were opaque wrapper messages; `requests` was imported but
+  not declared as a dependency.
+
+---
+
+<sub>Created and maintained by Mohammed Junaid and Muhammad Zahid.</sub>

{salla_gitpuller-1.0.2 → salla_gitpuller-1.1.0}/gitpuller/__init__.py

@@ -1,3 +1,8 @@
+"""gitpuller — auto-pull a git repo over SSH inside Mage pipelines.
+
+Public API is re-exported here so callers can ``from gitpuller import ...``.
+"""
+
 from .gitpull import GitPullExecutor
 from .alert_manager import AlertManager
 from .state_manager import StateManager, InMemoryStateManager, MageAIStateManager
@@ -5,7 +10,7 @@ from .slack_notifier import SlackNotifier
 from .utils import transform_custom, get_repo_path, get_env_base_path
 
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 __all__ = [
     "GitPullExecutor",
     "AlertManager",

{salla_gitpuller-1.0.2 → salla_gitpuller-1.1.0}/gitpuller/alert_manager.py

@@ -1,12 +1,21 @@
+"""Alert de-duplication: decides whether a failure should page Slack."""
+
 from datetime import datetime, timedelta
 from typing import Any, Dict, Optional, Tuple
 from .state_manager import StateManager, InMemoryStateManager, MageAIStateManager
 
-class AlertManager:    
+
+class AlertManager:
+    """Wraps a ``StateManager`` to suppress repeated identical alerts."""
+
     def __init__(self, state_manager: Optional[StateManager] = None, use_mage_ai: bool = False):
+        # Pick the backing store for "last alert" bookkeeping:
         if state_manager is not None:
+            # Caller supplied one explicitly.
             self.state_manager = state_manager
         elif use_mage_ai:
+            # Persist across runs via Mage global variables when available,
+            # otherwise degrade gracefully to in-memory (per-process) state.
             try:
                 self.state_manager = MageAIStateManager()
             except ImportError:
@@ -14,37 +23,43 @@ class AlertManager:
                 self.state_manager = InMemoryStateManager()
         else:
             self.state_manager = InMemoryStateManager()
-    
+
     def should_send_alert(
-        self, 
-        pipeline_uuid: str, 
-        current_error: str, 
+        self,
+        pipeline_uuid: str,
+        current_error: str,
         suppression_hours: int = 1
     ) -> Tuple[bool, Dict[str, Any]]:
-        
+        """
+        Decide whether to alert for ``current_error``.
+
+        Rule: alert immediately on a first-ever or *changed* error; for an
+        unchanged error, only re-alert once ``suppression_hours`` has elapsed.
+        Returns ``(should_send, previous_state)``.
+        """
         state = self.state_manager.load_alert_state(pipeline_uuid)
         last_error = state.get("last_error_message")
         last_alert_time_str = state.get("last_alert_time")
-        
-        # If no previous alert, always send
+
+        # No prior alert on record — always send.
         if not last_error or not last_alert_time_str:
             return True, {"last_error_message": None, "last_alert_time": None}
-        
-        # If error is different, always send
+
+        # A different error than last time — always send.
         if last_error != current_error:
             return True, {"last_error_message": last_error, "last_alert_time": last_alert_time_str}
-        
-        # Same error - check if enough time has passed
+
+        # Same error as last time — only re-send once the window has elapsed.
         try:
             last_alert_time = datetime.fromisoformat(last_alert_time_str)
             time_since_last_alert = datetime.now() - last_alert_time
-            
+
             if time_since_last_alert >= timedelta(hours=suppression_hours):
                 return True, {"last_error_message": last_error, "last_alert_time": last_alert_time_str}
             else:
                 return False, {"last_error_message": last_error, "last_alert_time": last_alert_time_str}
         except (ValueError, TypeError):
-            # If we can't parse the time, send the alert to be safe
+            # Unparseable timestamp — fail open and alert rather than stay silent.
             return True, {"last_error_message": last_error, "last_alert_time": last_alert_time_str}
     
     def save_alert_state(