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

wraith_cli-1.5.0/.pre-commit-config.yaml

@@ -0,0 +1,82 @@
+minimum_pre_commit_version: 4.0.0
+default_stages: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+        exclude: ^src/wraith_cli/assets\.py$
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+      - id: check-case-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.9
+    hooks:
+      - id: ruff
+        args: ["--fix", "--exit-non-zero-on-fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        types_or: [python, markdown, rst]
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+      - id: pyupgrade
+        args: [--py312-plus]
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.11.0.1
+    hooks:
+      - id: shellcheck
+        args: ["--severity=warning"]
+
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ["--baseline", ".secrets.baseline"]
+        exclude: package-lock.json
+
+  - repo: local
+    hooks:
+      - id: generate-docs
+        name: Auto-generate CLI Documentation
+        entry: uv run typer src/wraith_cli/main.py utils docs --output docs/usage.md
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: no-raw-print
+        name: Ban raw print() in favor of typer.echo/rich
+        language: pygrep
+        entry: '(?<![\.a-zA-Z0-9_])print\('
+        types: [python]
+
+      - id: ty-check
+        name: ty check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest-coverage
+        name: pytest-coverage
+        entry: ./bin/run_tests.sh
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: commitizen
+        name: commitizen check
+        entry: uv run cz check --commit-msg-file
+        language: system
+        stages: [commit-msg]

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wraith-cli
-Version: 1.3.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
@@ -64,35 +66,6 @@ Description-Content-Type: text/markdown
 high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
 for instant project scaffolding.
 
----
-
-## 🏗️ The Ghost Factory (New)
-
-The `spawn` command allows you to go from **Idea to Code** in under 5 seconds by
-bleaching a template and provisioning a private Gitea repository automatically.
-
-```bash
-wraith spawn my-new-api
-```
-
-1. **🧬 Clones** your `GHOST_TEMPLATE_URL`.
-2. **🧹 Bleaches** all previous git history.
-3. **🌐 Provisions** a new private repo via the Gitea API.
-4. **🚀 Pushes** the clean stack to your Sovereign remote.
-
----
-
-## 🛠️ Operational Manual
-
-| Command                  | Feature                | Status                                      |
-|--------------------------|------------------------|---------------------------------------------|
-| `wraith spawn <name>`    | **The Ghost Factory**  | 🏗️ Scaffolds new repos via Gitea API.       |
-| `wraith update`          | **Global Update**      | 🟢 PyPI-linked & `uv` powered.              |
-| `wraith ps`              | **Rich Observability** | 🟢 Sovereign Dark styling for Docker.       |
-| `wraith tail <svc>`      | **Flexible Logging**   | 🟢 Supports `--path` & Env Vars.            |
-| `wraith status`          | **Heartbeat**          | 🟢 Monitor OpenViking (Port 1933).          |
-| `wraith runner-reset`    | **Runner Defence**     | 🟢 CI/CD maintenance & registration wipe.  |
-| `wraith --version`       | **Self-Identity**      | 🟢 Eager callback for versioning.           |
 
 ---
 

{wraith_cli-1.3.0 → wraith_cli-1.5.0}/README.md

@@ -11,35 +11,6 @@
 high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
 for instant project scaffolding.
 
----
-
-## 🏗️ The Ghost Factory (New)
-
-The `spawn` command allows you to go from **Idea to Code** in under 5 seconds by
-bleaching a template and provisioning a private Gitea repository automatically.
-
-```bash
-wraith spawn my-new-api
-```
-
-1. **🧬 Clones** your `GHOST_TEMPLATE_URL`.
-2. **🧹 Bleaches** all previous git history.
-3. **🌐 Provisions** a new private repo via the Gitea API.
-4. **🚀 Pushes** the clean stack to your Sovereign remote.
-
----
-
-## 🛠️ Operational Manual
-
-| Command                  | Feature                | Status                                      |
-|--------------------------|------------------------|---------------------------------------------|
-| `wraith spawn <name>`    | **The Ghost Factory**  | 🏗️ Scaffolds new repos via Gitea API.       |
-| `wraith update`          | **Global Update**      | 🟢 PyPI-linked & `uv` powered.              |
-| `wraith ps`              | **Rich Observability** | 🟢 Sovereign Dark styling for Docker.       |
-| `wraith tail <svc>`      | **Flexible Logging**   | 🟢 Supports `--path` & Env Vars.            |
-| `wraith status`          | **Heartbeat**          | 🟢 Monitor OpenViking (Port 1933).          |
-| `wraith runner-reset`    | **Runner Defence**     | 🟢 CI/CD maintenance & registration wipe.  |
-| `wraith --version`       | **Self-Identity**      | 🟢 Eager callback for versioning.           |
 
 ---
 

wraith_cli-1.5.0/docs/usage.md

@@ -0,0 +1,245 @@
+# CLI
+
+Wraith Sovereign CLI: Ghost Stack Orchestrator
+
+**Usage**:
+
+```console
+$ [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--version`: Show version and exit.
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**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.
+* `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
+endpoint to verify if the orchestrator API is responsive.
+
+**Usage**:
+
+```console
+$ status [OPTIONS]
+```
+
+**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.
+
+Compares local versioning against the remote registry and
+automatically triggers an upgrade via 'uv tool' if a newer
+version is detected.
+
+**Usage**:
+
+```console
+$ update [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `ps`
+
+List running containers with Sovereign styling.
+
+Wraps 'docker ps' to provide a high-contrast,
+readable table summarising service names,
+container status, and source images.
+
+**Usage**:
+
+```console
+$ ps [OPTIONS]
+```
+
+**Options**:
+
+* `-a, --all`: Show all containers
+* `--help`: Show this message and exit.
+
+## `tail`
+
+Stream live logs from a specific service.
+
+Connects to a running container to output real-time logs.
+Resolves Compose paths via CLI flags,
+environment variables, or local directory discovery.
+
+Priority:
+   1. Passed flag --path
+   2. Configured compose_path
+   3. Discovered via search_roots
+   4. Current Directory
+
+**Usage**:
+
+```console
+$ tail [OPTIONS] SERVICE
+```
+
+**Arguments**:
+
+* `SERVICE`: Service name (e.g., ollama, gitea)  [required]
+
+**Options**:
+
+* `-p, --path PATH`: Path to directory with docker-compose.yml.
+* `--help`: Show this message and exit.
+
+## `runner-reset`
+
+Repair hung or offline Gitea Action Runners.
+
+Performs a nuclear reset: stops the container,
+purges the local registration data, and restarts
+the service to force a fresh handshake with Gitea.
+
+Requires GITEA_COMPOSE_PATH as an envelope variable
+
+**Usage**:
+
+```console
+$ runner-reset [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `spawn`
+
+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.
+
+**Usage**:
+
+```console
+$ spawn [OPTIONS] REPO_NAME
+```
+
+**Arguments**:
+
+* `REPO_NAME`: Name of the new Ghost Stack repository  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `logs`
+
+Unified hardware health and logging portal.
+
+Default behavior provides log-tailing instructions.
+Using the --health flag triggers a deep-dive query
+into the Scrutiny API for SMART drive data and disk temps.
+
+**Usage**:
+
+```console
+$ logs [OPTIONS]
+```
+
+**Options**:
+
+* `--health`: Pull SMART data summary from Scrutiny API
+* `--help`: Show this message and exit.
+
+## `mesh`
+
+Map the Tailscale Ghost Mesh network.
+
+Interrogates the Tailscale daemon (local or containerised)
+to return a list of active peers, their internal IPs, and
+current online/offline status.
+
+**Usage**:
+
+```console
+$ mesh [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `audit`
+
+Execute a Sovereign security and compliance scan.
+
+Audits the running stack for common vulnerabilities, including
+containers running with root privileges and exposed ports
+that deviate from the Registry Spec.
+
+**Usage**:
+
+```console
+$ audit [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.

{wraith_cli-1.3.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.3.0 → wraith_cli-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wraith-cli"
-version = "1.3.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/assets.py

@@ -0,0 +1,10 @@
+# fmt: off
+# DO NOT EDIT: Trailing whitespace here is structural, 
+# not "useless" linting noise.
+WRAITH_LOGO = r"""
+ ▖  ▖▄▖▄▖▄▖▄▖▖▖  ▄▖▖ ▄▖    
+ ▌▞▖▌▙▘▌▌▐ ▐ ▙▌▄▖▌ ▌ ▐     
+ ▛ ▝▌▌▌▛▌▟▖▐ ▌▌  ▙▖▙▖▟▖    
+                           
+"""
+# fmt: on

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