wraith-cli 1.4.0__tar.gz → 1.5.0__tar.gz

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/CHANGELOG.md

@@ -1,3 +1,5 @@
+## v1.5.0 (2026-04-06)
+
 ## v1.4.0 (2026-04-05)
 
 ## v1.3.0 (2026-04-04)

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wraith-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: Sovereign Command Centre for a Ghost Stack
 Project-URL: Homepage, https://git.thomaspeoples.com/thomaspeoples/wraith-cli
 Project-URL: Documentation, https://www.thomaspeoples.com/gitea-repos/wraith-cli/
@@ -32,7 +32,9 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.12
+Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: python-dotenv
+Requires-Dist: pyyaml>=6.0.1
 Requires-Dist: requests
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/docs/usage.md

@@ -17,22 +17,41 @@ $ [OPTIONS] COMMAND [ARGS]...
 
 **Commands**:
 
+* `init`: Bootstrap a new Wraith environment.
 * `status`: Check the heartbeat of the OpenViking Stack.
+* `health`: Visualise health of all configured services.
 * `update`: Sync Wraith with the latest PyPI release.
 * `ps`: List running containers with Sovereign...
 * `tail`: Stream live logs from a specific service.
 * `runner-reset`: Repair hung or offline Gitea Action Runners.
-* `spawn`: 🏭 Scaffold a new repository instantly.
+* `spawn`: Scaffold a new repository instantly.
 * `logs`: Unified hardware health and logging portal.
 * `mesh`: Map the Tailscale Ghost Mesh network.
 * `audit`: Execute a Sovereign security and...
 
+## `init`
+
+Bootstrap a new Wraith environment.
+
+Interactive wizard to configure the stack name, API URLs,
+and auto-probe for Docker and Tailscale presence.
+
+**Usage**:
+
+```console
+$ init [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
 ## `status`
 
 Check the heartbeat of the OpenViking Stack.
 
- Polls the configured VIKING_BASE_URL health
-nendpoint to verify if the orchestrator API is responsive.
+Polls the configured VIKING_BASE_URL health
+endpoint to verify if the orchestrator API is responsive.
 
 **Usage**:
 
@@ -44,6 +63,23 @@ $ status [OPTIONS]
 
 * `--help`: Show this message and exit.
 
+## `health`
+
+Visualise health of all configured services.
+
+Polls the health_url for each service defined in .wraith.yaml.
+Automatically parses OpenAPI/Swagger specs to find /health endpoints.
+
+**Usage**:
+
+```console
+$ health [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
 ## `update`
 
 Sync Wraith with the latest PyPI release.
@@ -91,8 +127,9 @@ environment variables, or local directory discovery.
 
 Priority:
    1. Passed flag --path
-   2. Env Var WRAITH_COMPOSE_PATH
-   3. Current Directory
+   2. Configured compose_path
+   3. Discovered via search_roots
+   4. Current Directory
 
 **Usage**:
 
@@ -106,7 +143,7 @@ $ tail [OPTIONS] SERVICE
 
 **Options**:
 
-* `-p, --path PATH`: Path to directory with docker-compose.yml.  [env var: WRAITH_COMPOSE_PATH]
+* `-p, --path PATH`: Path to directory with docker-compose.yml.
 * `--help`: Show this message and exit.
 
 ## `runner-reset`
@@ -131,7 +168,7 @@ $ runner-reset [OPTIONS]
 
 ## `spawn`
 
-🏭 Scaffold a new repository instantly.
+Scaffold a new repository instantly.
 
 Atomic scaffolding for new Ghost Stack repositories.
 Clones a template, bleaches git history,

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/mkdocs.yml

@@ -35,4 +35,3 @@ extra:
     - icon: material/home
       link: https://www.thomaspeoples.com/
       name: Back to Main Site
-

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wraith-cli"
-version = "1.4.0"
+version = "1.5.0"
 description = "Sovereign Command Centre for a Ghost Stack"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -27,6 +27,8 @@ dependencies = [
     "python-dotenv",
     "rich>=13.0.0",
     "typer>=0.9.0",
+    "pydantic-settings>=2.0.0",
+    "pyyaml>=6.0.1",
 ]
 
 [project.urls]

wraith_cli-1.5.0/src/wraith_cli/config.py

@@ -0,0 +1,134 @@
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import yaml
+from pydantic import AliasChoices, BaseModel, Field, HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class ServiceModel(BaseModel):
+    path: Path
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    health_url: HttpUrl | None = None
+
+
+class TemplateModel(BaseModel):
+    url: str
+
+
+class WraithSettings(BaseSettings):
+    stack_name: str = "Ghost Stack"
+    viking_api: HttpUrl | None = None
+    search_roots: list[Path] = Field(default_factory=list)
+    services: dict[str, ServiceModel] = Field(default_factory=dict)
+    docker_enabled: bool = False
+    tailscale_enabled: bool = False
+
+    # Provider Settings
+    forge_api_url: str | None = None
+    forge_token: str | None = None
+    forge_type: str = "gitea"
+    templates: dict[str, TemplateModel] = Field(default_factory=dict)
+
+    # Legacy .env mappings
+    gitea_api_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("WRAITH_GITEA_API_URL", "GITEA_API_URL"),
+    )
+    gitea_token: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("WRAITH_GITEA_TOKEN", "GITEA_TOKEN"),
+    )
+    gitea_template_url: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "WRAITH_GITEA_TEMPLATE_URL", "GITEA_TEMPLATE_URL"
+        ),
+    )
+    gitea_compose_path: Path | None = Field(
+        default=None,
+        validation_alias=AliasChoices(
+            "WRAITH_GITEA_COMPOSE_PATH", "GITEA_COMPOSE_PATH"
+        ),
+    )
+    compose_path: Path | None = Field(
+        default=None,
+        validation_alias=AliasChoices("WRAITH_COMPOSE_PATH", "COMPOSE_PATH"),
+    )
+
+    # Ingests .env variables as fallback, prioritizing WRAITH_ prefix
+    model_config = SettingsConfigDict(
+        env_prefix="WRAITH_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+
+@lru_cache
+def get_settings() -> WraithSettings:
+    """
+    Load settings with priority:
+    1. Local .wraith.yaml (CWD)
+    2. User ~/.config/wraith/config.yaml
+    3. Environment variables (WRAITH_ prefix & .env fallback)
+    """
+    yaml_data: dict[str, Any] = {}
+
+    # 2. User-level config
+    user_config = Path.home() / ".config" / "wraith" / "config.yaml"
+    if user_config.exists():  # pragma: no cover
+        with open(user_config) as f:
+            parsed = yaml.safe_load(f)
+            if isinstance(parsed, dict):
+                yaml_data.update(parsed)
+
+    # 1. Local config (overrides user-level)
+    local_config = Path.cwd() / ".wraith.yaml"
+    if local_config.exists():  # pragma: no cover
+        with open(local_config) as f:
+            parsed = yaml.safe_load(f)
+            if isinstance(parsed, dict):
+                yaml_data.update(parsed)
+
+    # Pydantic BaseSettings kwargs override environment variables.
+    return WraithSettings(**yaml_data)
+
+
+def discover_service(
+    service_name: str, search_roots: list[Path]
+) -> Path | None:  # pragma: no cover
+    """
+    Recursively search for docker-compose.yml files in search_roots.
+    Matches if the directory name or container_name equals the service_name.
+    """
+    for root in search_roots:
+        if not root.exists() or not root.is_dir():
+            continue
+
+        for compose_file in root.rglob("docker-compose.yml"):
+            # Match by directory name
+            if compose_file.parent.name == service_name:
+                return compose_file
+
+            # Match by container_name or service key in yaml
+            try:
+                with open(compose_file) as f:
+                    compose_data = yaml.safe_load(f)
+                    if compose_data and isinstance(compose_data, dict):
+                        services = compose_data.get("services", {})
+                        for svc_key, svc_def in services.items():
+                            if svc_key == service_name:
+                                return compose_file
+                            if (
+                                isinstance(svc_def, dict)
+                                and svc_def.get("container_name")
+                                == service_name
+                            ):
+                                return compose_file
+            except Exception:
+                pass  # Ignore unparsable files during discovery
+
+    return None

{wraith_cli-1.4.0 → wraith_cli-1.5.0}/src/wraith_cli/main.py

@@ -1,18 +1,20 @@
-import os
 import subprocess
 from importlib.metadata import version as get_local_version
 from pathlib import Path
 from typing import Annotated
+from urllib.parse import urljoin
 
 import requests
 import typer
-from dotenv import load_dotenv
+import yaml
 from rich.align import Align
 from rich.markdown import Markdown
 from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+from rich.table import Table
 from rich.text import Text
 
-from wraith_cli import assets, qol, repo_make, shield
+from wraith_cli import assets, config, qol, repo_make, shield
 
 SOVEREIGN_ADVISORY = """
 ## Sovereign Security Advisory – Please Read
@@ -29,23 +31,13 @@ Recommended baseline:
 - Audit environment variable scope (`GITEA_COMPOSE_PATH`, etc.)
 """
 
-# Load environment variables from .env
-load_dotenv()
-
 # Initialise Typer App
 app = typer.Typer(
     help="Wraith Sovereign CLI: Ghost Stack Orchestrator",
     rich_markup_mode="rich",
 )
 
-# --- Configuration ---
-VIKING_URL = os.getenv(
-    "VIKING_BASE_URL", "http://127.0.0.1:1933/api/v1"
-).rstrip("/")
-GITEA_PATH = os.getenv("GITEA_COMPOSE_PATH")
-GITEA_API_URL = os.getenv("GITEA_API_URL")
-GITEA_TOKEN = os.getenv("GITEA_TOKEN")
-GITEA_TEMPLATE_URL = os.getenv("GITEA_TEMPLATE_URL")
+SETTINGS = config.get_settings()
 
 
 # --- Callbacks ---
@@ -63,7 +55,7 @@ def version_callback(value: bool):
 
 
 def print_wraith_welcome():  # pragma: no cover
-    """Renders the definitive OpenClaw-inspired Sovereign splash."""
+    """Renders the definitive Sovereign splash."""
     console = qol.console
     local_v = get_local_version("wraith-cli")
 
@@ -121,15 +113,73 @@ def main(
 # --- Commands ---
 
 
+@app.command()
+def init():  # pragma: no cover
+    """
+    Bootstrap a new Wraith environment.
+
+    Interactive wizard to configure the stack name, API URLs,
+    and auto-probe for Docker and Tailscale presence.
+    """
+    typer.echo("Initialising Wraith Sovereign Environment...")
+    stack_name = Prompt.ask("Stack Name", default="Ghost Stack")
+    viking_api = Prompt.ask("Viking API URL (optional)", default="")
+
+    if viking_api:
+        try:
+            typer.echo(f"🔍 Validating API: {viking_api}")
+            resp = requests.head(viking_api, timeout=3)
+            resp.raise_for_status()
+        except Exception as e:
+            typer.secho(f"⚠️ API Validation failed: {e}", fg="yellow")
+            if not Confirm.ask("Proceed anyway?", default=True):
+                raise typer.Exit(1) from e
+
+    typer.echo("🔍 Probing environment...")
+    docker_res = subprocess.run(
+        ["docker", "info"], capture_output=True, check=False
+    )
+    docker_enabled = docker_res.returncode == 0
+    d_msg = "✅ Found" if docker_enabled else "❌ Not Found"
+    typer.echo(f"   └── Docker: {d_msg}")
+
+    tailscale_res = subprocess.run(
+        ["tailscale", "status"], capture_output=True, check=False
+    )
+    tailscale_enabled = tailscale_res.returncode == 0
+    ts_msg = "✅ Found" if tailscale_enabled else "❌ Not Found"
+    typer.echo(f"   └── Tailscale: {ts_msg}")
+
+    yaml_data = {
+        "stack_name": stack_name,
+        "docker_enabled": docker_enabled,
+        "tailscale_enabled": tailscale_enabled,
+    }
+    if viking_api:
+        yaml_data["viking_api"] = viking_api
+
+    out_path = Path.cwd() / ".wraith.yaml"
+    with open(out_path, "w") as f:
+        yaml.dump(yaml_data, f, sort_keys=False)
+
+    typer.secho(f"✨ Configuration saved to {out_path}", fg="green", bold=True)
+
+
 @app.command()
 def status():
     """
-     Check the heartbeat of the OpenViking Stack.
+    Check the heartbeat of the OpenViking Stack.
 
-     Polls the configured VIKING_BASE_URL health
-    nendpoint to verify if the orchestrator API is responsive.
+    Polls the configured VIKING_BASE_URL health
+    endpoint to verify if the orchestrator API is responsive.
     """
-    url = f"{VIKING_URL}/health"
+    settings = config.get_settings()
+    viking_url = (
+        str(settings.viking_api).rstrip("/")
+        if settings.viking_api
+        else "http://127.0.0.1:1933/api/v1"
+    )
+    url = f"{viking_url}/health"
     try:
         response = requests.get(url, timeout=3)
         if response.status_code == 200:
@@ -143,6 +193,67 @@ def status():
         typer.secho("🔴 OpenViking: Offline", fg=typer.colors.RED)
 
 
+@app.command()
+def health():  # pragma: no cover
+    """
+    Visualise health of all configured services.
+
+    Polls the health_url for each service defined in .wraith.yaml.
+    Automatically parses OpenAPI/Swagger specs to find /health endpoints.
+    """
+    table = Table(title=f"{SETTINGS.stack_name} - Service Health")
+    table.add_column("Service", style="cyan")
+    table.add_column("Status", style="bold")
+    table.add_column("Details")
+
+    if not SETTINGS.services:
+        typer.secho("No services configured in .wraith.yaml", fg="yellow")
+        return
+
+    for name, svc in SETTINGS.services.items():
+        if not svc.health_url:
+            table.add_row(
+                name, "[yellow]Unknown[/yellow]", "No health_url configured"
+            )
+            continue
+
+        url = str(svc.health_url)
+        try:
+            resp = requests.get(url, timeout=5)
+
+            # OpenAPI Schema Intelligence
+            if "application/json" in resp.headers.get("Content-Type", ""):
+                data = resp.json()
+                is_spec = isinstance(data, dict) and (
+                    "openapi" in data or "swagger" in data
+                )
+                if is_spec:
+                    paths = data.get("paths", {})
+                    health_endpoint = None
+                    for ep in ["/health", "/status"]:
+                        if ep in paths:
+                            health_endpoint = ep
+                            break
+
+                    if health_endpoint:
+                        actual_url = urljoin(url, health_endpoint)
+                        resp = requests.get(actual_url, timeout=5)
+                        url = actual_url
+
+            if resp.status_code == 200:
+                table.add_row(
+                    name, "[green]Online[/green]", f"HTTP 200 ({url})"
+                )
+            else:
+                table.add_row(
+                    name, f"[yellow]Warning ({resp.status_code})[/yellow]", url
+                )
+        except Exception as e:
+            table.add_row(name, "[red]Offline[/red]", str(e))
+
+    qol.console.print(table)
+
+
 @app.command()
 def update():
     """
@@ -167,7 +278,7 @@ def update():
         typer.secho(f"❌ Update check failed: {e}", fg="red")
 
 
-@app.command()
+@app.command(hidden=not SETTINGS.docker_enabled)
 def ps(
     all: Annotated[
         bool, typer.Option("--all", "-a", help="Show all containers")
@@ -180,19 +291,16 @@ def ps(
     readable table summarising service names,
     container status, and source images.
     """
-    cmd = ["docker", "ps"]
-    if all:
-        cmd.append("-a")
-
-    # Custom format for our Rich table conversion
-    cmd.extend(["--format", "table {{.Names}}\t{{.Status}}\t{{.Image}}"])
+    from wraith_cli.providers import get_docker_provider
 
-    result = subprocess.run(cmd, capture_output=True, text=True)
-    if result.returncode != 0:
-        typer.secho("❌ Docker is not running or accessible.", fg="red")
+    docker = get_docker_provider()
+    try:
+        stdout = docker.ps(all=all)
+    except RuntimeError as e:
+        typer.secho(f"❌ {e}", fg="red")
         return
 
-    rich_table = qol.format_docker_table(result.stdout)
+    rich_table = qol.format_docker_table(stdout)
     qol.console.print(rich_table)
 
 
@@ -206,7 +314,6 @@ def tail(
         typer.Option(
             "--path",
             "-p",
-            envvar="WRAITH_COMPOSE_PATH",
             help="Path to directory with docker-compose.yml.",
         ),
     ] = None,
@@ -220,10 +327,19 @@ def tail(
 
     Priority:
        1. Passed flag --path
-       2. Env Var WRAITH_COMPOSE_PATH
-       3. Current Directory
+       2. Configured compose_path
+       3. Discovered via search_roots
+       4. Current Directory
     """
-    target_path = path or Path.cwd()
+    settings = config.get_settings()
+    target_path = path or settings.compose_path
+
+    if not target_path and settings.search_roots:
+        discovered = config.discover_service(service, settings.search_roots)
+        if discovered:
+            target_path = discovered.parent
+
+    target_path = target_path or Path.cwd()
 
     typer.echo(f"🔍 Searching for {service} in {target_path}...")
     success = qol.run_tail(service, target_path)
@@ -246,11 +362,20 @@ def runner_reset():
 
     Requires GITEA_COMPOSE_PATH as an envelope variable
     """
-    if not GITEA_PATH:
-        typer.secho("❌ Error: GITEA_COMPOSE_PATH not set in .env", fg="red")
+    settings = config.get_settings()
+    compose_path = settings.gitea_compose_path
+
+    if not compose_path and settings.search_roots:
+        discovered = config.discover_service(
+            "act_runner", settings.search_roots
+        )
+        if discovered:
+            compose_path = discovered.parent
+
+    if not compose_path:
+        typer.secho("❌ Error: GITEA_COMPOSE_PATH not set in config", fg="red")
         raise typer.Exit(1)
 
-    compose_path = Path(GITEA_PATH)
     docker_file = compose_path / "docker-compose.yml"
     runner_data = compose_path / "data/act_runner/.runner"
 
@@ -277,43 +402,54 @@ def spawn(
     ),
 ):
     """
-    🏭 Scaffold a new repository instantly.
+    Scaffold a new repository instantly.
 
     Atomic scaffolding for new Ghost Stack repositories.
     Clones a template, bleaches git history,
     provisions a remote repository via API, and
     pushes the initial commit in one sequence.
     """
-    if not all([GITEA_API_URL, GITEA_TOKEN, GITEA_TEMPLATE_URL]):
+    settings = config.get_settings()
+    if not all([
+        settings.forge_api_url,
+        settings.forge_token,
+        settings.templates,
+    ]):
         typer.secho(
-            """❌ Missing Environment Variables!
-            Check .env for
-                GITEA_API_URL,
-                GITEA_TOKEN,
-                and GITEA_TEMPLATE_URL.
+            """❌ Missing Configuration!
+            Check config for
+                forge_api_url,
+                forge_token,
+                and templates.
             """,
             fg="red",
         )
         raise typer.Exit(1)
 
-    assert GITEA_API_URL is not None
-    assert GITEA_TOKEN is not None
-    assert GITEA_TEMPLATE_URL is not None
+    assert settings.forge_api_url is not None
+    assert settings.forge_token is not None
 
     target_dir = Path.cwd() / repo_name
     typer.echo(f"👻 Spawning '{repo_name}' from Repo Factory...")
 
     try:
         typer.echo("   └── 🧬 Cloning template and bleaching history...")
-        repo_make.clone_and_bleach(GITEA_TEMPLATE_URL, target_dir, GITEA_TOKEN)
-
-        typer.echo("   └── 🌐 Provisioning repository on Gitea...")
-        remote_url = repo_make.create_gitea_repo(
-            repo_name, GITEA_API_URL, GITEA_TOKEN
+        # Use default template or fallback to first available
+        template = settings.templates.get(
+            "default", next(iter(settings.templates.values()))
         )
+        repo_make.clone_and_bleach(
+            template.url, target_dir, settings.forge_token
+        )
+
+        typer.echo("   └── 🌐 Provisioning repository on Forge...")
+        from wraith_cli.providers import get_forge_provider
+
+        forge = get_forge_provider(settings)
+        remote_url = forge.create_repo(repo_name)
 
         typer.echo(f"   └── 🚀 Initialising and pushing to {remote_url}...")
-        repo_make.init_and_push(target_dir, remote_url, GITEA_TOKEN)
+        repo_make.init_and_push(target_dir, remote_url, settings.forge_token)
 
         typer.secho(
             f"\n✅ Success! Gitea Repo '{repo_name}' is alive.",
@@ -356,7 +492,7 @@ def logs(
         )
 
 
-@app.command()
+@app.command(hidden=not SETTINGS.tailscale_enabled)
 def mesh():
     """
     Map the Tailscale Ghost Mesh network.