wraith-cli 1.6.0__tar.gz → 1.7.0__tar.gz

wraith_cli-1.7.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run *)",
+      "Bash(./bin/run_tests.sh)",
+      "Bash(git add *)",
+      "Bash(git commit -m '👻 feature/TJP-12062: add enterprise NAS management suite *)",
+      "Bash(python3 -)",
+      "Bash(git -C /home/thomaspeoples/pjt-nas/nas/SovereignDocs/gitea-repos status --short)",
+      "Bash(git -C /home/thomaspeoples/pjt-nas/nas/SovereignDocs/gitea-repos branch --show-current)"
+    ]
+  }
+}

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/CHANGELOG.md

@@ -1,3 +1,5 @@
+## v1.7.0 (2026-06-12)
+
 ## v1.6.0 (2026-04-07)
 
 ## v1.5.0 (2026-04-06)

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wraith-cli
-Version: 1.6.0
+Version: 1.7.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/
@@ -60,12 +60,35 @@ Description-Content-Type: text/markdown
 
 
 # 👻 Wraith-CLI
-### *Sovereign Orchestration for the Ghost Stack*
+### *Sovereign Orchestration & NAS Management for the Ghost Stack*
 
 **Wraith-CLI** is the nervous system of the Ghost Stack. It bridges the gap between
-high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
-for instant project scaffolding.
+high-level container orchestration and bare-metal reality — instant project scaffolding,
+container operations, and a full NAS management suite in one binary.
 
+---
+
+## 🗄️ NAS Management Suite
+
+| Command | Purpose |
+|---|---|
+| `wraith disks` | Physical disk inventory — model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with configurable warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart /dev/sda` | SMART verdict + failure-predicting attributes per drive |
+| `wraith shares` | NFS exports and Samba shares, guest access flagged |
+| `wraith snap` | ZFS/btrfs snapshot create / list / prune (safe by design) |
+| `wraith doctor` | Full health check suite — cron-friendly exit codes, webhook/ntfy alerts |
+| `wraith report` | Timestamped markdown/JSON audit reports |
+
+Every read-only command takes `--json` — pipe Wraith straight into dashboards,
+monitoring stacks, or fleet tooling. Unattended monitoring is one cron line:
+
+```cron
+*/30 * * * * wraith doctor --notify
+```
+
+See the [NAS Management docs](docs/nas.md) for full coverage.
 
 ---
 

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/README.md

@@ -5,12 +5,35 @@
 
 
 # 👻 Wraith-CLI
-### *Sovereign Orchestration for the Ghost Stack*
+### *Sovereign Orchestration & NAS Management for the Ghost Stack*
 
 **Wraith-CLI** is the nervous system of the Ghost Stack. It bridges the gap between
-high-level container orchestration and bare-metal reality, providing the "Ghost Factory"
-for instant project scaffolding.
+high-level container orchestration and bare-metal reality — instant project scaffolding,
+container operations, and a full NAS management suite in one binary.
 
+---
+
+## 🗄️ NAS Management Suite
+
+| Command | Purpose |
+|---|---|
+| `wraith disks` | Physical disk inventory — model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with configurable warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart /dev/sda` | SMART verdict + failure-predicting attributes per drive |
+| `wraith shares` | NFS exports and Samba shares, guest access flagged |
+| `wraith snap` | ZFS/btrfs snapshot create / list / prune (safe by design) |
+| `wraith doctor` | Full health check suite — cron-friendly exit codes, webhook/ntfy alerts |
+| `wraith report` | Timestamped markdown/JSON audit reports |
+
+Every read-only command takes `--json` — pipe Wraith straight into dashboards,
+monitoring stacks, or fleet tooling. Unattended monitoring is one cron line:
+
+```cron
+*/30 * * * * wraith doctor --notify
+```
+
+See the [NAS Management docs](docs/nas.md) for full coverage.
 
 ---
 

wraith_cli-1.7.0/docs/nas.md

@@ -0,0 +1,88 @@
+# NAS Management
+
+Wraith turns your Ghost Stack node into a fully managed NAS. The
+suite covers hardware introspection, capacity monitoring, share
+discovery, snapshot lifecycle, and automated health enforcement —
+all from one binary, all scriptable via `--json`.
+
+## Command Overview
+
+| Command | What it does |
+|---|---|
+| `wraith disks` | Physical disk inventory: model, serial, capacity, HDD/SSD, bus |
+| `wraith storage` | Filesystem usage with warn/crit thresholds |
+| `wraith raid` | mdraid array and ZFS pool health |
+| `wraith smart <device>` | Per-drive SMART verdict and failure-predicting attributes |
+| `wraith shares` | NFS exports and Samba shares, guest-access flagged |
+| `wraith snap` | ZFS/btrfs snapshot list / create / prune |
+| `wraith doctor` | Full health check suite with exit codes and alerting |
+| `wraith report` | Point-in-time audit report (markdown or JSON) |
+
+Every read-only command accepts `--json` for machine-readable
+output, making Wraith a drop-in data source for dashboards,
+monitoring pipelines, and fleet tooling.
+
+## The Doctor
+
+`wraith doctor` is the heartbeat of the system. It checks:
+
+- Docker daemon responsiveness
+- Tailscale mesh connectivity
+- Storage utilisation against configured thresholds
+- RAID array and ZFS pool degradation
+- SMART self-assessment on every physical disk
+- HTTP health of every configured stack service
+
+It exits non-zero when anything is critical, so it slots straight
+into cron:
+
+```cron
+*/30 * * * * wraith doctor --notify || logger "NAS degraded"
+```
+
+With `--notify`, warn/crit findings are pushed to your configured
+webhook or [ntfy](https://ntfy.sh) topic.
+
+## Configuration
+
+Add to `.wraith.yaml`:
+
+```yaml
+storage_warn_pct: 80
+storage_crit_pct: 90
+alerts:
+  webhook_url: https://ntfy.sh/my-nas-alerts
+  kind: ntfy        # or "webhook" for a JSON POST
+```
+
+## Snapshots
+
+Snapshot lifecycle management with a safety guarantee: `snap prune`
+only ever considers snapshots Wraith itself created (the `wraith-`
+prefix). Manual snapshots are never touched.
+
+```bash
+wraith snap create tank/data          # ZFS, auto-named
+wraith snap create /srv/data --btrfs-dest /srv/.snapshots/nightly
+wraith snap list tank/data
+wraith snap prune tank/data --keep 7  # confirm before destroy
+```
+
+A nightly rotation is two cron lines:
+
+```cron
+0 2 * * * wraith snap create tank/data
+30 2 * * * wraith snap prune tank/data --keep 14 --yes
+```
+
+## Audit Reports
+
+`wraith report` captures disks, storage, RAID state, and the full
+doctor suite into a timestamped document — an audit trail for
+compliance, capacity planning, or a paper trail before and after
+hardware changes.
+
+```bash
+wraith report                          # markdown, timestamped name
+wraith report -f json -o nightly.json  # feed it to anything
+```

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/docs/usage.md

@@ -28,6 +28,14 @@ $ [OPTIONS] COMMAND [ARGS]...
 * `logs`: Unified hardware health and logging portal.
 * `mesh`: Map the Tailscale Ghost Mesh network.
 * `audit`: Execute a Sovereign security and...
+* `disks`: Inventory the physical disks in this NAS.
+* `storage`: Show filesystem usage across all mounted...
+* `raid`: Report RAID array and ZFS pool health.
+* `smart`: Deep-dive SMART health for a single drive.
+* `shares`: List network shares exposed by this NAS.
+* `doctor`: Run the full NAS health check suite.
+* `report`: Generate a point-in-time NAS health report.
+* `snap`: Manage ZFS/btrfs snapshots.
 
 ## `init`
 
@@ -243,3 +251,219 @@ $ audit [OPTIONS]
 **Options**:
 
 * `--help`: Show this message and exit.
+
+## `disks`
+
+Inventory the physical disks in this NAS.
+
+Enumerates block devices with model, serial, capacity,
+media type (HDD/SSD), bus, and active mountpoints.
+
+**Usage**:
+
+```console
+$ disks [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `storage`
+
+Show filesystem usage across all mounted volumes.
+
+Colour-codes utilisation against the configured warn/crit
+thresholds (storage_warn_pct / storage_crit_pct).
+
+**Usage**:
+
+```console
+$ storage [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `raid`
+
+Report RAID array and ZFS pool health.
+
+Parses /proc/mdstat for Linux software RAID and queries
+zpool for ZFS pool state. Degraded arrays surface in red.
+
+**Usage**:
+
+```console
+$ raid [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `smart`
+
+Deep-dive SMART health for a single drive.
+
+Pulls the self-assessment verdict, temperature, power-on
+hours, and failure-predicting attributes via smartctl.
+
+**Usage**:
+
+```console
+$ smart [OPTIONS] DEVICE
+```
+
+**Arguments**:
+
+* `DEVICE`: Block device path (e.g. /dev/sda)  [required]
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `shares`
+
+List network shares exposed by this NAS.
+
+Discovers NFS exports (/etc/exports) and Samba shares
+(smb.conf), flagging guest-accessible SMB shares.
+
+**Usage**:
+
+```console
+$ shares [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+## `doctor`
+
+Run the full NAS health check suite.
+
+Checks Docker, Tailscale, storage thresholds, RAID/pool
+health, per-disk SMART status, and service endpoints.
+Exits non-zero on any critical finding — cron-friendly.
+
+**Usage**:
+
+```console
+$ doctor [OPTIONS]
+```
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--notify`: Send warn/crit findings to the configured webhook.
+* `--help`: Show this message and exit.
+
+## `report`
+
+Generate a point-in-time NAS health report.
+
+Captures disks, storage, RAID state, and the full doctor
+check suite into a timestamped markdown or JSON document —
+an audit trail for compliance and capacity planning.
+
+**Usage**:
+
+```console
+$ report [OPTIONS]
+```
+
+**Options**:
+
+* `-o, --output PATH`: Report file destination.
+* `-f, --format TEXT`: Report format: md or json.  [default: md]
+* `--help`: Show this message and exit.
+
+## `snap`
+
+Manage ZFS/btrfs snapshots.
+
+**Usage**:
+
+```console
+$ snap [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `list`: List ZFS snapshots, newest last.
+* `create`: Create a snapshot of a ZFS dataset or...
+* `prune`: Prune old wraith-created snapshots from a...
+
+### `snap list`
+
+List ZFS snapshots, newest last.
+
+**Usage**:
+
+```console
+$ snap list [OPTIONS] [DATASET]
+```
+
+**Arguments**:
+
+* `[DATASET]`: Limit to one ZFS dataset.
+
+**Options**:
+
+* `--json`: Emit machine-readable JSON.
+* `--help`: Show this message and exit.
+
+### `snap create`
+
+Create a snapshot of a ZFS dataset or btrfs subvolume.
+
+**Usage**:
+
+```console
+$ snap create [OPTIONS] TARGET
+```
+
+**Arguments**:
+
+* `TARGET`: ZFS dataset (pool/data) or btrfs subvolume path.  [required]
+
+**Options**:
+
+* `-n, --name TEXT`: Snapshot name override.
+* `--btrfs-dest TEXT`: Treat target as btrfs subvolume; snapshot here.
+* `--help`: Show this message and exit.
+
+### `snap prune`
+
+Prune old wraith-created snapshots from a dataset.
+
+Only snapshots named with the wraith- prefix are candidates;
+manually created snapshots are never touched.
+
+**Usage**:
+
+```console
+$ snap prune [OPTIONS] DATASET
+```
+
+**Arguments**:
+
+* `DATASET`: ZFS dataset to prune.  [required]
+
+**Options**:
+
+* `-k, --keep INTEGER`: Snapshots to retain.  [default: 7]
+* `-y, --yes`: Skip confirmation prompt.
+* `--help`: Show this message and exit.

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/mkdocs.yml

@@ -19,6 +19,7 @@ theme:
 nav:
   - Home: index.md
   - Usage: usage.md
+  - NAS Management: nas.md
   - Technical Reference: reference.md
   - Architecture Reference: architecture.md
   - Security Statement: security.md

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wraith-cli"
-version = "1.6.0"
+version = "1.7.0"
 description = "Sovereign Command Centre for a Ghost Stack"
 readme = "README.md"
 requires-python = ">=3.12"

{wraith_cli-1.6.0 → wraith_cli-1.7.0}/src/wraith_cli/config.py

@@ -17,6 +17,11 @@ class TemplateModel(BaseModel):
     url: str
 
 
+class AlertsModel(BaseModel):
+    webhook_url: str | None = None
+    kind: str = "webhook"  # "webhook" (JSON POST) or "ntfy" (text POST)
+
+
 class WraithSettings(BaseSettings):
     stack_name: str = "Ghost Stack"
     viking_api: HttpUrl | None = None
@@ -25,6 +30,11 @@ class WraithSettings(BaseSettings):
     docker_enabled: bool = False
     tailscale_enabled: bool = False
 
+    # NAS management
+    alerts: AlertsModel = Field(default_factory=AlertsModel)
+    storage_warn_pct: int = 80
+    storage_crit_pct: int = 90
+
     # Provider Settings
     forge_api_url: str | None = None
     forge_token: str | None = None

wraith_cli-1.7.0/src/wraith_cli/doctor.py

@@ -0,0 +1,216 @@
+"""Full-stack NAS health check engine.
+
+Each check returns {"name", "status", "detail"} where status is one
+of: ok, warn, crit, skip. The CLI maps any crit to a non-zero exit
+code so `wraith doctor` slots straight into cron and CI.
+"""
+
+import shutil
+import subprocess
+from typing import Any
+
+import requests
+from rich.table import Table
+
+from wraith_cli import nas
+from wraith_cli.config import WraithSettings
+
+OK = "ok"
+WARN = "warn"
+CRIT = "crit"
+SKIP = "skip"
+
+
+def _check(name: str, status: str, detail: str) -> dict[str, str]:
+    return {"name": name, "status": status, "detail": detail}
+
+
+def check_docker(settings: WraithSettings) -> dict[str, str]:
+    if not settings.docker_enabled:
+        return _check("docker", SKIP, "Disabled in config")
+    result = subprocess.run(
+        ["docker", "info"], capture_output=True, check=False
+    )
+    if result.returncode == 0:
+        return _check("docker", OK, "Daemon responsive")
+    return _check("docker", CRIT, "Docker daemon unreachable")
+
+
+def check_tailscale(settings: WraithSettings) -> dict[str, str]:
+    if not settings.tailscale_enabled:
+        return _check("tailscale", SKIP, "Disabled in config")
+    result = subprocess.run(
+        ["tailscale", "status"], capture_output=True, check=False
+    )
+    if result.returncode == 0:
+        return _check("tailscale", OK, "Mesh connected")
+    return _check("tailscale", CRIT, "Tailscale down — mesh unreachable")
+
+
+def check_storage(settings: WraithSettings) -> list[dict[str, str]]:
+    try:
+        usage = nas.get_storage(
+            settings.storage_warn_pct, settings.storage_crit_pct
+        )
+    except Exception as e:
+        return [_check("storage", WARN, f"Could not read usage: {e}")]
+
+    checks = []
+    for u in usage:
+        status = {"ok": OK, "warn": WARN, "crit": CRIT}[u["level"]]
+        checks.append(
+            _check(
+                f"storage {u['mount']}",
+                status,
+                f"{u['used_pct']}% used, "
+                f"{nas.human_bytes(u['free_bytes'])} free",
+            )
+        )
+    return checks or [_check("storage", WARN, "No filesystems found")]
+
+
+def check_raid() -> list[dict[str, str]]:
+    try:
+        raid = nas.get_raid_status()
+    except Exception as e:
+        return [_check("raid", WARN, f"Could not read RAID state: {e}")]
+
+    checks = []
+    for arr in raid["mdraid"]:
+        if arr["healthy"]:
+            checks.append(
+                _check(f"mdraid {arr['name']}", OK, arr["detail"] or "active")
+            )
+        else:
+            checks.append(
+                _check(
+                    f"mdraid {arr['name']}",
+                    CRIT,
+                    f"DEGRADED: {arr['detail']}",
+                )
+            )
+    for pool in raid["zpools"]:
+        status = OK if pool["healthy"] else CRIT
+        checks.append(_check(f"zpool {pool['name']}", status, pool["health"]))
+    return checks or [_check("raid", SKIP, "No arrays or pools")]
+
+
+def check_smart() -> list[dict[str, str]]:
+    if shutil.which("smartctl") is None:
+        return [_check("smart", SKIP, "smartmontools not installed")]
+    try:
+        disks = nas.get_disks()
+    except Exception as e:
+        return [_check("smart", WARN, f"Disk enumeration failed: {e}")]
+
+    checks = []
+    for disk in disks:
+        try:
+            smart = nas.get_smart(disk["path"])
+        except Exception as e:
+            checks.append(_check(f"smart {disk['path']}", WARN, str(e)))
+            continue
+        bad_attrs = {
+            k: v
+            for k, v in smart["attributes"].items()
+            if k != "Available Spare %" and v
+        }
+        if not smart["passed"]:
+            checks.append(
+                _check(
+                    f"smart {disk['path']}",
+                    CRIT,
+                    "SMART self-assessment FAILED",
+                )
+            )
+        elif bad_attrs:
+            detail = ", ".join(f"{k}={v}" for k, v in bad_attrs.items())
+            checks.append(_check(f"smart {disk['path']}", WARN, detail))
+        else:
+            checks.append(_check(f"smart {disk['path']}", OK, "Healthy"))
+    return checks or [_check("smart", SKIP, "No disks found")]
+
+
+def check_services(settings: WraithSettings) -> list[dict[str, str]]:
+    if not settings.services:
+        return [_check("services", SKIP, "No services configured")]
+    checks = []
+    for name, svc in settings.services.items():
+        if not svc.health_url:
+            checks.append(_check(f"service {name}", SKIP, "No health_url"))
+            continue
+        try:
+            resp = requests.get(str(svc.health_url), timeout=5)
+            if resp.status_code == 200:
+                checks.append(_check(f"service {name}", OK, "HTTP 200"))
+            else:
+                checks.append(
+                    _check(
+                        f"service {name}",
+                        WARN,
+                        f"HTTP {resp.status_code}",
+                    )
+                )
+        except requests.exceptions.RequestException:
+            checks.append(_check(f"service {name}", CRIT, "Unreachable"))
+    return checks
+
+
+def run_doctor(settings: WraithSettings) -> dict[str, Any]:
+    """Run the full check suite and summarise."""
+    checks: list[dict[str, str]] = []
+    checks.append(check_docker(settings))
+    checks.append(check_tailscale(settings))
+    checks.extend(check_storage(settings))
+    checks.extend(check_raid())
+    checks.extend(check_smart())
+    checks.extend(check_services(settings))
+
+    counts = {OK: 0, WARN: 0, CRIT: 0, SKIP: 0}
+    for c in checks:
+        counts[c["status"]] += 1
+
+    if counts[CRIT]:
+        verdict = CRIT
+    elif counts[WARN]:
+        verdict = WARN
+    else:
+        verdict = OK
+
+    return {"verdict": verdict, "counts": counts, "checks": checks}
+
+
+def render_doctor(result: dict[str, Any]) -> Table:
+    styles = {
+        OK: "[green]OK[/green]",
+        WARN: "[yellow]WARN[/yellow]",
+        CRIT: "[red]CRIT[/red]",
+        SKIP: "[bright_black]SKIP[/bright_black]",
+    }
+    counts = result["counts"]
+    title = (
+        f"Wraith Doctor — {counts[OK]} ok, {counts[WARN]} warn, "
+        f"{counts[CRIT]} crit, {counts[SKIP]} skipped"
+    )
+    table = Table(
+        title=title,
+        border_style="bright_black",
+        header_style="bold green",
+    )
+    table.add_column("Check", style="cyan")
+    table.add_column("Status")
+    table.add_column("Detail")
+
+    for c in result["checks"]:
+        table.add_row(c["name"], styles[c["status"]], c["detail"])
+    return table
+
+
+def summarise_failures(result: dict[str, Any]) -> str:
+    """One-line-per-failure summary for alert payloads."""
+    lines = [
+        f"[{c['status'].upper()}] {c['name']}: {c['detail']}"
+        for c in result["checks"]
+        if c["status"] in (WARN, CRIT)
+    ]
+    return "\n".join(lines)