waitfor-cli 0.1.0__py3-none-any.whl

waitfor/__init__.py

@@ -0,0 +1,3 @@
+"""waitfor - Wait for conditions in automation and scripts."""
+
+__version__ = "0.1.0"

waitfor/cli.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""waitfor - Wait for conditions (port, file, URL, process) in automation scripts."""
+
+import click
+import socket
+import time
+import os
+import sys
+import json
+import subprocess
+from pathlib import Path
+from typing import Optional, Callable, Any, Dict
+from urllib.request import urlopen, Request
+from urllib.error import URLError, HTTPError
+
+
+def wait_loop(
+    check_fn: Callable[[], bool],
+    condition_name: str,
+    timeout: int,
+    interval: float,
+    quiet: bool,
+    json_output: bool,
+    invert: bool = False
+) -> Dict[str, Any]:
+    """Generic wait loop. Returns result dict."""
+    start = time.time()
+    attempts = 0
+    
+    while True:
+        attempts += 1
+        elapsed = time.time() - start
+        
+        try:
+            result = check_fn()
+            # If invert, we want the check to be False
+            success = (not result) if invert else result
+        except Exception as e:
+            if not quiet and not json_output:
+                click.echo(f"  Check error: {e}", err=True)
+            success = invert  # Error counts as False, which is success if inverted
+        
+        if success:
+            result_data = {
+                "success": True,
+                "condition": condition_name,
+                "elapsed_seconds": round(elapsed, 2),
+                "attempts": attempts
+            }
+            if json_output:
+                click.echo(json.dumps(result_data))
+            elif not quiet:
+                click.echo(f"✓ {condition_name} (took {elapsed:.1f}s, {attempts} attempts)")
+            return result_data
+        
+        if timeout > 0 and elapsed >= timeout:
+            result_data = {
+                "success": False,
+                "condition": condition_name,
+                "elapsed_seconds": round(elapsed, 2),
+                "attempts": attempts,
+                "error": f"Timeout after {timeout}s"
+            }
+            if json_output:
+                click.echo(json.dumps(result_data))
+            elif not quiet:
+                click.echo(f"✗ Timeout waiting for {condition_name}", err=True)
+            return result_data
+        
+        if not quiet and not json_output:
+            click.echo(f"  Waiting for {condition_name}... ({elapsed:.0f}s)", err=True)
+        
+        time.sleep(interval)
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """Wait for conditions in automation scripts.
+    
+    Useful for waiting on services, files, or processes before continuing.
+    
+    Examples:
+    
+        waitfor port 8080
+        
+        waitfor file /tmp/ready.flag
+        
+        waitfor url http://localhost:3000/health
+        
+        waitfor process nginx
+    """
+    pass
+
+
+@cli.command("port")
+@click.argument("port", type=int)
+@click.option("-h", "--host", default="localhost", help="Host to check")
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=1.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--closed", is_flag=True, help="Wait for port to be CLOSED instead")
+def wait_port(port: int, host: str, timeout: int, interval: float, quiet: bool, json_output: bool, closed: bool):
+    """Wait for a TCP port to be open (or closed with --closed)."""
+    
+    def check_port():
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(1)
+        try:
+            result = sock.connect_ex((host, port))
+            return result == 0
+        finally:
+            sock.close()
+    
+    action = "closed" if closed else "open"
+    condition = f"port {port} on {host} to be {action}"
+    result = wait_loop(check_port, condition, timeout, interval, quiet, json_output, invert=closed)
+    sys.exit(0 if result["success"] else 1)
+
+
+@cli.command("file")
+@click.argument("path")
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=1.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--gone", is_flag=True, help="Wait for file to be GONE instead")
+@click.option("--contains", "content", help="Wait for file to contain this string")
+def wait_file(path: str, timeout: int, interval: float, quiet: bool, json_output: bool, gone: bool, content: Optional[str]):
+    """Wait for a file to exist (or be gone with --gone)."""
+    
+    def check_file():
+        p = Path(path)
+        if not p.exists():
+            return False
+        if content:
+            try:
+                return content in p.read_text()
+            except:
+                return False
+        return True
+    
+    if content:
+        condition = f"file {path} to contain '{content}'"
+    elif gone:
+        condition = f"file {path} to be gone"
+    else:
+        condition = f"file {path} to exist"
+    
+    result = wait_loop(check_file, condition, timeout, interval, quiet, json_output, invert=gone)
+    sys.exit(0 if result["success"] else 1)
+
+
+@cli.command("url")
+@click.argument("url")
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=2.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--status", type=int, help="Expected HTTP status code (default: any 2xx)")
+@click.option("--contains", "content", help="Response must contain this string")
+def wait_url(url: str, timeout: int, interval: float, quiet: bool, json_output: bool, status: Optional[int], content: Optional[str]):
+    """Wait for a URL to respond successfully."""
+    
+    def check_url():
+        try:
+            req = Request(url, headers={"User-Agent": "waitfor/1.0"})
+            resp = urlopen(req, timeout=5)
+            code = resp.getcode()
+            
+            if status and code != status:
+                return False
+            elif not status and not (200 <= code < 300):
+                return False
+            
+            if content:
+                body = resp.read().decode("utf-8", errors="ignore")
+                return content in body
+            
+            return True
+        except (URLError, HTTPError):
+            return False
+    
+    condition = f"URL {url} to respond"
+    if status:
+        condition += f" with status {status}"
+    if content:
+        condition += f" containing '{content}'"
+    
+    result = wait_loop(check_url, condition, timeout, interval, quiet, json_output)
+    sys.exit(0 if result["success"] else 1)
+
+
+@cli.command("process")
+@click.argument("name")
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=1.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--gone", is_flag=True, help="Wait for process to be GONE instead")
+def wait_process(name: str, timeout: int, interval: float, quiet: bool, json_output: bool, gone: bool):
+    """Wait for a process to be running (or gone with --gone)."""
+    
+    def check_process():
+        try:
+            # Use pgrep for cross-platform process detection
+            result = subprocess.run(
+                ["pgrep", "-x", name],
+                capture_output=True,
+                timeout=5
+            )
+            return result.returncode == 0
+        except:
+            # Fallback: check ps output
+            try:
+                result = subprocess.run(
+                    ["ps", "aux"],
+                    capture_output=True,
+                    text=True,
+                    timeout=5
+                )
+                return name in result.stdout
+            except:
+                return False
+    
+    action = "to stop" if gone else "to start"
+    condition = f"process '{name}' {action}"
+    result = wait_loop(check_process, condition, timeout, interval, quiet, json_output, invert=gone)
+    sys.exit(0 if result["success"] else 1)
+
+
+@cli.command("command")
+@click.argument("cmd")
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=2.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+@click.option("--shell/--no-shell", default=True, help="Run through shell")
+def wait_command(cmd: str, timeout: int, interval: float, quiet: bool, json_output: bool, shell: bool):
+    """Wait for a command to exit with status 0."""
+    
+    def check_command():
+        try:
+            result = subprocess.run(
+                cmd,
+                shell=shell,
+                capture_output=True,
+                timeout=10
+            )
+            return result.returncode == 0
+        except:
+            return False
+    
+    condition = f"command '{cmd}' to succeed"
+    result = wait_loop(check_command, condition, timeout, interval, quiet, json_output)
+    sys.exit(0 if result["success"] else 1)
+
+
+@cli.command("tcp")
+@click.argument("host")
+@click.argument("port", type=int)
+@click.option("-t", "--timeout", default=30, help="Timeout in seconds (0=forever)")
+@click.option("-i", "--interval", default=1.0, help="Check interval in seconds")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress output")
+@click.option("--json", "json_output", is_flag=True, help="JSON output")
+def wait_tcp(host: str, port: int, timeout: int, interval: float, quiet: bool, json_output: bool):
+    """Wait for a remote TCP connection (host + port)."""
+    
+    def check_tcp():
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(2)
+        try:
+            result = sock.connect_ex((host, port))
+            return result == 0
+        finally:
+            sock.close()
+    
+    condition = f"TCP connection to {host}:{port}"
+    result = wait_loop(check_tcp, condition, timeout, interval, quiet, json_output)
+    sys.exit(0 if result["success"] else 1)
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()

waitfor_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: waitfor-cli
+Version: 0.1.0
+Summary: Wait for conditions (port, file, URL, process) in automation scripts
+Author-email: Marcus <marcus.builds.things@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/marcusbuildsthings-droid/waitfor
+Project-URL: Repository, https://github.com/marcusbuildsthings-droid/waitfor
+Project-URL: Issues, https://github.com/marcusbuildsthings-droid/waitfor/issues
+Keywords: cli,automation,wait,port,process,devops,scripting
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Dynamic: license-file
+
+# waitfor
+
+Wait for conditions in automation scripts. Check for ports, files, URLs, or processes before continuing.
+
+## Installation
+
+```bash
+pip install waitfor-cli
+```
+
+## Usage
+
+### Wait for a port to be open
+
+```bash
+# Wait for port 8080 on localhost
+waitfor port 8080
+
+# Wait for port on remote host
+waitfor port 5432 -h db.example.com
+
+# Wait for port to be CLOSED
+waitfor port 8080 --closed
+```
+
+### Wait for a file
+
+```bash
+# Wait for file to exist
+waitfor file /tmp/ready.flag
+
+# Wait for file to be gone
+waitfor file /var/run/app.pid --gone
+
+# Wait for file to contain specific content
+waitfor file /var/log/app.log --contains "Server started"
+```
+
+### Wait for a URL to respond
+
+```bash
+# Wait for health endpoint
+waitfor url http://localhost:3000/health
+
+# Wait for specific status code
+waitfor url http://api.example.com/status --status 200
+
+# Wait for response to contain string
+waitfor url http://localhost:8080/ready --contains "ok"
+```
+
+### Wait for a process
+
+```bash
+# Wait for process to start
+waitfor process nginx
+
+# Wait for process to stop
+waitfor process nginx --gone
+```
+
+### Wait for a command to succeed
+
+```bash
+# Wait for docker container to be healthy
+waitfor command "docker inspect --format='{{.State.Health.Status}}' myapp | grep healthy"
+
+# Wait for database to accept connections
+waitfor command "pg_isready -h localhost"
+```
+
+### Wait for remote TCP connection
+
+```bash
+# Wait for database to be reachable
+waitfor tcp db.example.com 5432
+
+# Wait for Redis
+waitfor tcp localhost 6379
+```
+
+## Options
+
+All commands support these common options:
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --timeout` | Timeout in seconds (0 = forever) | 30 |
+| `-i, --interval` | Check interval in seconds | 1.0-2.0 |
+| `-q, --quiet` | Suppress output | off |
+| `--json` | JSON output | off |
+
+## Exit Codes
+
+- `0` - Condition met
+- `1` - Timeout or condition not met
+
+## JSON Output
+
+```bash
+$ waitfor port 8080 --json
+{"success": true, "condition": "port 8080 on localhost to be open", "elapsed_seconds": 0.01, "attempts": 1}
+```
+
+## Examples
+
+### Wait for services before running tests
+
+```bash
+#!/bin/bash
+waitfor port 5432 -t 60 && \
+waitfor port 6379 -t 30 && \
+waitfor url http://localhost:8080/health -t 60 && \
+pytest
+```
+
+### Deployment script
+
+```bash
+#!/bin/bash
+docker-compose up -d
+
+# Wait for all services
+waitfor port 80 -t 120
+waitfor url http://localhost/api/health --contains "healthy" -t 60
+
+echo "Deployment complete!"
+```
+
+### Wait for build artifact
+
+```bash
+# Start build in background
+make build &
+
+# Wait for output
+waitfor file ./dist/app.js -t 300
+```
+
+## For AI Agents
+
+See [SKILL.md](SKILL.md) for agent-optimized documentation.
+
+## License
+
+MIT

waitfor_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+waitfor/__init__.py,sha256=Ck2AXo82-T6hZI5nIR9HGIBfXAT-iULduLwyHotaV90,86
+waitfor/cli.py,sha256=9swfOCo-KnotMofHz2JlegTy8A2HDJVzA01hnJjA18k,10447
+waitfor_cli-0.1.0.dist-info/licenses/LICENSE,sha256=9tNBpWq8KGbuJqmeComp40OiNnbvpvsKn1YP26PUtck,1063
+waitfor_cli-0.1.0.dist-info/METADATA,sha256=zeagwZc_fyKSpJCaM8BzfpWRPXpU8e4O2yCUbIyOlug,4015
+waitfor_cli-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+waitfor_cli-0.1.0.dist-info/entry_points.txt,sha256=UB6yg40JW5YcC8VtL8Ucqq0LOuvBEM6AUVZ4L6TAbqs,45
+waitfor_cli-0.1.0.dist-info/top_level.txt,sha256=CZo7W0FVVs1rRLRxwZNeooeRORiEHQdz21OYVUoMpWI,8
+waitfor_cli-0.1.0.dist-info/RECORD,,

waitfor_cli-0.1.0.dist-info/WHEEL

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

waitfor_cli-0.1.0.dist-info/entry_points.txt

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

waitfor_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus
+
+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.

waitfor_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+waitfor