plexavo 0.2.0__tar.gz → 0.2.2__tar.gz

{plexavo-0.2.0 → plexavo-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source AWS misconfiguration scanner — runs with your own local AWS credentials, nothing sent to anyone else.
 Author: Kavee
 License: AGPL-3.0-or-later
@@ -127,20 +127,24 @@ scoped by a Condition block, or a CloudTrail lookup that hit its page cap on
 
 ## Quick start
 
-**Recommended: [uv](https://docs.astral.sh/uv/).** It installs Plexavo into
-its own isolated environment automatically — no venv to create, activate,
-or remember to reactivate in every new terminal.
+The install path depends on your OS — **uv on macOS & Linux**, **pip on
+Windows**. Either way it's a one-command install with no venv to create,
+activate, or reactivate in every new terminal.
 
-### 1. Install uv (if you don't already have it)
+### macOS & Linux — uv
+
+[uv](https://docs.astral.sh/uv/) installs Plexavo into its own isolated
+environment automatically.
+
+**1. Install uv** (if you don't already have it):
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh          # Mac/Linux
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 (Full options: [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).)
 
-### 2. Install Plexavo
+**2. Install Plexavo:**
 
 ```bash
 uv tool install plexavo
@@ -178,12 +182,60 @@ uv tool upgrade plexavo
 uv tool uninstall plexavo
 ```
 
-### 3. Run a scan
+### Windows — pip
+
+Install with `pip` and run the tool as `py -m plexavo`:
+
+```powershell
+py -m pip install --user plexavo
+py -m plexavo
+```
+
+`py -m plexavo` with no arguments opens the interactive menu, exactly
+like the `plexavo` command does on macOS/Linux — flags are only for
+scripting/CI.
+
+> **Why not uv/pipx on Windows?** Both work by putting a small generated
+> `plexavo.exe` launcher on your PATH. That launcher is unsigned, and
+> Windows Smart App Control blocks unsigned executables it doesn't
+> recognise — so `plexavo` can fail to start with a "can't confirm who
+> published" message. `py -m plexavo` calls Python directly and never
+> touches that launcher, so it always works. (If your machine doesn't
+> enforce Smart App Control, `uv tool install plexavo` works here too.)
+
+**AI-narrated explanations** (see [Cost](#cost)):
+
+```powershell
+py -m pip install --user "plexavo[ai]"
+```
+
+Updating or removing later:
+
+```powershell
+py -m pip install --user --upgrade plexavo
+py -m pip uninstall plexavo
+```
+
+### Optional: type `plexavo` instead of `py -m plexavo`
+
+Add a shortcut to your PowerShell profile once:
+
+```powershell
+Add-Content $PROFILE 'function plexavo { py -m plexavo @args }'
+```
+
+Open a new terminal and `plexavo` then works just like it does on
+macOS/Linux.
+
+### Run a scan
 
 ```bash
 plexavo scan --profile my-aws-profile --report-html report.html
 ```
 
+(On Windows without the shortcut above: `py -m plexavo scan --profile
+my-aws-profile --report-html report.html`.)
+
 No `--profile`? It uses your default profile / environment variables,
 same resolution order as the AWS CLI. No AI, no API key, no cost — and
 findings still come with free Next Step / Full Fix Detail guidance
@@ -213,19 +265,24 @@ plexavo scan --profile my-aws-profile --explain --report-html report.html --repo
 
 ### Alternative: pipx
 
-Already use [pipx](https://pipx.pypa.io/)? It works exactly the same way —
-its own isolated environment, one global command, no venv:
+Already use [pipx](https://pipx.pypa.io/) on macOS/Linux? It works exactly
+the same way as uv — its own isolated environment, one global command, no
+venv:
 
 ```bash
 pipx install plexavo
 pipx install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
+On Windows, pipx has the same Smart App Control caveat as uv (see the
+Windows section above) — if the `plexavo` command is blocked, run
+`py -m plexavo` instead, or use the `pip` install.
+
 ### Alternative: pip + venv
 
-Prefer to manage the environment yourself, or on a system without uv/pipx?
-Modern Python (PEP 668) blocks a plain `pip install` outside a venv on
-many systems, so create one first:
+Want full isolation and prefer to manage the environment yourself? Modern
+Python (PEP 668) blocks a plain `pip install` outside a venv on many
+Linux and Homebrew setups, so create one first:
 
 ```bash
 python -m venv plexavo-env
@@ -238,7 +295,9 @@ pip install "plexavo[ai]"   # with AI-narrated explanations
 
 You'll need to reactivate this venv (`plexavo-env\Scripts\activate` /
 `source plexavo-env/bin/activate`) every time you open a new terminal —
-`deactivate` exits it without uninstalling anything.
+`deactivate` exits it without uninstalling anything. On Windows, run
+`python -m plexavo` if the `plexavo` command is blocked by Smart App
+Control.
 
 ### From source (for contributing, or trying an unreleased change)
 
@@ -257,6 +316,7 @@ plexavo/
 ├── findings.py                  # Finding data model, Severity enum
 ├── scoring.py                    # 0-100 score from a list of Findings
 ├── cli.py                         # `plexavo scan ...` entry point
+├── __main__.py                      # lets `python -m plexavo` run the CLI
 ├── checks/
 │   ├── iam.py                       # IAM-01 to IAM-06 (privilege escalation)
 │   ├── iam_hygiene.py                # IAM-07 to IAM-14 (hygiene, cross-account trust)

{plexavo-0.2.0 → plexavo-0.2.2}/README.md

@@ -98,20 +98,24 @@ scoped by a Condition block, or a CloudTrail lookup that hit its page cap on
 
 ## Quick start
 
-**Recommended: [uv](https://docs.astral.sh/uv/).** It installs Plexavo into
-its own isolated environment automatically — no venv to create, activate,
-or remember to reactivate in every new terminal.
+The install path depends on your OS — **uv on macOS & Linux**, **pip on
+Windows**. Either way it's a one-command install with no venv to create,
+activate, or reactivate in every new terminal.
 
-### 1. Install uv (if you don't already have it)
+### macOS & Linux — uv
+
+[uv](https://docs.astral.sh/uv/) installs Plexavo into its own isolated
+environment automatically.
+
+**1. Install uv** (if you don't already have it):
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh          # Mac/Linux
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 (Full options: [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).)
 
-### 2. Install Plexavo
+**2. Install Plexavo:**
 
 ```bash
 uv tool install plexavo
@@ -149,12 +153,60 @@ uv tool upgrade plexavo
 uv tool uninstall plexavo
 ```
 
-### 3. Run a scan
+### Windows — pip
+
+Install with `pip` and run the tool as `py -m plexavo`:
+
+```powershell
+py -m pip install --user plexavo
+py -m plexavo
+```
+
+`py -m plexavo` with no arguments opens the interactive menu, exactly
+like the `plexavo` command does on macOS/Linux — flags are only for
+scripting/CI.
+
+> **Why not uv/pipx on Windows?** Both work by putting a small generated
+> `plexavo.exe` launcher on your PATH. That launcher is unsigned, and
+> Windows Smart App Control blocks unsigned executables it doesn't
+> recognise — so `plexavo` can fail to start with a "can't confirm who
+> published" message. `py -m plexavo` calls Python directly and never
+> touches that launcher, so it always works. (If your machine doesn't
+> enforce Smart App Control, `uv tool install plexavo` works here too.)
+
+**AI-narrated explanations** (see [Cost](#cost)):
+
+```powershell
+py -m pip install --user "plexavo[ai]"
+```
+
+Updating or removing later:
+
+```powershell
+py -m pip install --user --upgrade plexavo
+py -m pip uninstall plexavo
+```
+
+### Optional: type `plexavo` instead of `py -m plexavo`
+
+Add a shortcut to your PowerShell profile once:
+
+```powershell
+Add-Content $PROFILE 'function plexavo { py -m plexavo @args }'
+```
+
+Open a new terminal and `plexavo` then works just like it does on
+macOS/Linux.
+
+### Run a scan
 
 ```bash
 plexavo scan --profile my-aws-profile --report-html report.html
 ```
 
+(On Windows without the shortcut above: `py -m plexavo scan --profile
+my-aws-profile --report-html report.html`.)
+
 No `--profile`? It uses your default profile / environment variables,
 same resolution order as the AWS CLI. No AI, no API key, no cost — and
 findings still come with free Next Step / Full Fix Detail guidance
@@ -184,19 +236,24 @@ plexavo scan --profile my-aws-profile --explain --report-html report.html --repo
 
 ### Alternative: pipx
 
-Already use [pipx](https://pipx.pypa.io/)? It works exactly the same way —
-its own isolated environment, one global command, no venv:
+Already use [pipx](https://pipx.pypa.io/) on macOS/Linux? It works exactly
+the same way as uv — its own isolated environment, one global command, no
+venv:
 
 ```bash
 pipx install plexavo
 pipx install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
+On Windows, pipx has the same Smart App Control caveat as uv (see the
+Windows section above) — if the `plexavo` command is blocked, run
+`py -m plexavo` instead, or use the `pip` install.
+
 ### Alternative: pip + venv
 
-Prefer to manage the environment yourself, or on a system without uv/pipx?
-Modern Python (PEP 668) blocks a plain `pip install` outside a venv on
-many systems, so create one first:
+Want full isolation and prefer to manage the environment yourself? Modern
+Python (PEP 668) blocks a plain `pip install` outside a venv on many
+Linux and Homebrew setups, so create one first:
 
 ```bash
 python -m venv plexavo-env
@@ -209,7 +266,9 @@ pip install "plexavo[ai]"   # with AI-narrated explanations
 
 You'll need to reactivate this venv (`plexavo-env\Scripts\activate` /
 `source plexavo-env/bin/activate`) every time you open a new terminal —
-`deactivate` exits it without uninstalling anything.
+`deactivate` exits it without uninstalling anything. On Windows, run
+`python -m plexavo` if the `plexavo` command is blocked by Smart App
+Control.
 
 ### From source (for contributing, or trying an unreleased change)
 
@@ -228,6 +287,7 @@ plexavo/
 ├── findings.py                  # Finding data model, Severity enum
 ├── scoring.py                    # 0-100 score from a list of Findings
 ├── cli.py                         # `plexavo scan ...` entry point
+├── __main__.py                      # lets `python -m plexavo` run the CLI
 ├── checks/
 │   ├── iam.py                       # IAM-01 to IAM-06 (privilege escalation)
 │   ├── iam_hygiene.py                # IAM-07 to IAM-14 (hygiene, cross-account trust)

{plexavo-0.2.0 → plexavo-0.2.2}/plexavo/__init__.py

@@ -4,4 +4,4 @@ Runs entirely with your own local AWS credentials. Nothing is sent to
 anyone else. See README.md for usage, or `plexavo scan --help`.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

plexavo-0.2.2/plexavo/__main__.py

@@ -0,0 +1,13 @@
+"""Allow `python -m plexavo` (and `py -m plexavo` on Windows) to launch the CLI.
+
+This is the exact same entry point as the installed `plexavo` command, so
+running it with no arguments still opens the interactive menu. It exists so
+Windows users can install with plain `pip` and run the tool without going
+through the generated `plexavo.exe` launcher, which Windows Smart App Control
+blocks on some machines (it's unsigned). See the README's Quick start.
+"""
+
+from plexavo.cli import main
+
+if __name__ == "__main__":
+    main()

{plexavo-0.2.0 → plexavo-0.2.2}/plexavo/auth.py

@@ -11,7 +11,7 @@ your own credentials, and nothing leaves your machine.
 from __future__ import annotations
 
 import boto3
-from botocore.exceptions import NoCredentialsError, ProfileNotFound
+from botocore.exceptions import ClientError, NoCredentialsError, ProfileNotFound
 
 
 def get_local_session(profile_name: str | None = None, region: str | None = None) -> boto3.Session:
@@ -50,6 +50,14 @@ def get_local_session(profile_name: str | None = None, region: str | None = None
             f"{f'--profile {profile_name} ' if profile_name else ''}"
             "to set them up."
         ) from e
+    except ClientError as e:
+        code = e.response.get("Error", {}).get("Code", "Unknown")
+        raise RuntimeError(
+            f"AWS rejected these credentials ({code}). The access key may "
+            "be invalid, deactivated, or deleted — run `aws configure "
+            f"{f'--profile {profile_name} ' if profile_name else ''}"
+            "` to update them."
+        ) from e
 
     return boto3.Session(profile_name=profile_name, region_name=resolved_region)
 

{plexavo-0.2.0 → plexavo-0.2.2}/plexavo/interactive.py

@@ -16,10 +16,10 @@ import os
 
 import boto3
 from rich import box
-from rich.align import Align
-from rich.console import Console
+from rich.console import Console, Group
 from rich.panel import Panel
 from rich.prompt import Confirm, IntPrompt, Prompt
+from rich.table import Table
 from rich.text import Text
 
 from plexavo import __version__
@@ -42,27 +42,57 @@ FEATURES = [
     "100% local scanning — your AWS credentials never leave this machine",
 ]
 
-def _splash_panel() -> Panel:
-    header = Text()
-    header.append("PLEXAVO", style="bold white")
-    header.append("  ")
-    header.append(f"v{__version__}", style="grey62")
+def _gradient_wordmark(word: str, min_shade: int = 90, max_shade: int = 255) -> Text:
+    """Letter-spaced word with a symmetric grey -> white -> grey shimmer,
+    one shade per letter (a smooth peak at the center, not a linear ramp),
+    e.g. "P L E X A V O" fading brightest at the middle letter."""
+    text = Text()
+    n = len(word)
+    for i, ch in enumerate(word):
+        t = 1 - abs((i / (n - 1)) * 2 - 1) if n > 1 else 1.0
+        shade = round(min_shade + t * (max_shade - min_shade))
+        text.append(ch, style=f"bold #{shade:02x}{shade:02x}{shade:02x}")
+        if i != n - 1:
+            text.append(" ")
+    return text
+
+
+CLOUD_ART = (
+    "     .--.    \n"
+    "  .-(    ).  \n"
+    " (___.__)__) "
+)
+
+
+def _header_row() -> Table:
+    """Wordmark pinned to the left corner, a small ASCII cloud floating
+    in the opposite corner — a quiet logomark, not a centerpiece."""
+    wordmark = _gradient_wordmark("PLEXAVO")
+    wordmark.append("  ")
+    wordmark.append(f"v{__version__}", style="grey62")
+
+    grid = Table.grid(expand=True)
+    grid.add_column(ratio=1)
+    grid.add_column(justify="right")
+    grid.add_row(wordmark, Text(CLOUD_ART, style="grey50"))
+    return grid
+
 
+def _splash_panel() -> Panel:
     body = Text()
-    body.append_text(header)
-    body.append("\n")
     body.append("AWS Security Reimagined", style="italic grey74")
     body.append("\n")
     body.append(WEBSITE, style="underline grey62")
     body.append("\n\n")
-    body.append("FEATURES\n", style="bold grey74")
+    body.append("─" * 50, style="grey42")
+    body.append("\n\n")
     for i, feature in enumerate(FEATURES):
-        body.append(f"  · {feature}", style="grey66")
+        body.append(f"  ▸ {feature}", style="grey66")
         if i != len(FEATURES) - 1:
             body.append("\n")
 
     return Panel(
-        Align.center(body),
+        Group(_header_row(), body),
         border_style="grey50",
         box=box.ROUNDED,
         padding=(1, 4),

{plexavo-0.2.0 → plexavo-0.2.2}/plexavo.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexavo
-Version: 0.2.0
+Version: 0.2.2
 Summary: Open-source AWS misconfiguration scanner — runs with your own local AWS credentials, nothing sent to anyone else.
 Author: Kavee
 License: AGPL-3.0-or-later
@@ -127,20 +127,24 @@ scoped by a Condition block, or a CloudTrail lookup that hit its page cap on
 
 ## Quick start
 
-**Recommended: [uv](https://docs.astral.sh/uv/).** It installs Plexavo into
-its own isolated environment automatically — no venv to create, activate,
-or remember to reactivate in every new terminal.
+The install path depends on your OS — **uv on macOS & Linux**, **pip on
+Windows**. Either way it's a one-command install with no venv to create,
+activate, or reactivate in every new terminal.
 
-### 1. Install uv (if you don't already have it)
+### macOS & Linux — uv
+
+[uv](https://docs.astral.sh/uv/) installs Plexavo into its own isolated
+environment automatically.
+
+**1. Install uv** (if you don't already have it):
 
 ```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh          # Mac/Linux
-powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
+curl -LsSf https://astral.sh/uv/install.sh | sh
 ```
 
 (Full options: [uv installation docs](https://docs.astral.sh/uv/getting-started/installation/).)
 
-### 2. Install Plexavo
+**2. Install Plexavo:**
 
 ```bash
 uv tool install plexavo
@@ -178,12 +182,60 @@ uv tool upgrade plexavo
 uv tool uninstall plexavo
 ```
 
-### 3. Run a scan
+### Windows — pip
+
+Install with `pip` and run the tool as `py -m plexavo`:
+
+```powershell
+py -m pip install --user plexavo
+py -m plexavo
+```
+
+`py -m plexavo` with no arguments opens the interactive menu, exactly
+like the `plexavo` command does on macOS/Linux — flags are only for
+scripting/CI.
+
+> **Why not uv/pipx on Windows?** Both work by putting a small generated
+> `plexavo.exe` launcher on your PATH. That launcher is unsigned, and
+> Windows Smart App Control blocks unsigned executables it doesn't
+> recognise — so `plexavo` can fail to start with a "can't confirm who
+> published" message. `py -m plexavo` calls Python directly and never
+> touches that launcher, so it always works. (If your machine doesn't
+> enforce Smart App Control, `uv tool install plexavo` works here too.)
+
+**AI-narrated explanations** (see [Cost](#cost)):
+
+```powershell
+py -m pip install --user "plexavo[ai]"
+```
+
+Updating or removing later:
+
+```powershell
+py -m pip install --user --upgrade plexavo
+py -m pip uninstall plexavo
+```
+
+### Optional: type `plexavo` instead of `py -m plexavo`
+
+Add a shortcut to your PowerShell profile once:
+
+```powershell
+Add-Content $PROFILE 'function plexavo { py -m plexavo @args }'
+```
+
+Open a new terminal and `plexavo` then works just like it does on
+macOS/Linux.
+
+### Run a scan
 
 ```bash
 plexavo scan --profile my-aws-profile --report-html report.html
 ```
 
+(On Windows without the shortcut above: `py -m plexavo scan --profile
+my-aws-profile --report-html report.html`.)
+
 No `--profile`? It uses your default profile / environment variables,
 same resolution order as the AWS CLI. No AI, no API key, no cost — and
 findings still come with free Next Step / Full Fix Detail guidance
@@ -213,19 +265,24 @@ plexavo scan --profile my-aws-profile --explain --report-html report.html --repo
 
 ### Alternative: pipx
 
-Already use [pipx](https://pipx.pypa.io/)? It works exactly the same way —
-its own isolated environment, one global command, no venv:
+Already use [pipx](https://pipx.pypa.io/) on macOS/Linux? It works exactly
+the same way as uv — its own isolated environment, one global command, no
+venv:
 
 ```bash
 pipx install plexavo
 pipx install "plexavo[ai]"   # with AI-narrated explanations
 ```
 
+On Windows, pipx has the same Smart App Control caveat as uv (see the
+Windows section above) — if the `plexavo` command is blocked, run
+`py -m plexavo` instead, or use the `pip` install.
+
 ### Alternative: pip + venv
 
-Prefer to manage the environment yourself, or on a system without uv/pipx?
-Modern Python (PEP 668) blocks a plain `pip install` outside a venv on
-many systems, so create one first:
+Want full isolation and prefer to manage the environment yourself? Modern
+Python (PEP 668) blocks a plain `pip install` outside a venv on many
+Linux and Homebrew setups, so create one first:
 
 ```bash
 python -m venv plexavo-env
@@ -238,7 +295,9 @@ pip install "plexavo[ai]"   # with AI-narrated explanations
 
 You'll need to reactivate this venv (`plexavo-env\Scripts\activate` /
 `source plexavo-env/bin/activate`) every time you open a new terminal —
-`deactivate` exits it without uninstalling anything.
+`deactivate` exits it without uninstalling anything. On Windows, run
+`python -m plexavo` if the `plexavo` command is blocked by Smart App
+Control.
 
 ### From source (for contributing, or trying an unreleased change)
 
@@ -257,6 +316,7 @@ plexavo/
 ├── findings.py                  # Finding data model, Severity enum
 ├── scoring.py                    # 0-100 score from a list of Findings
 ├── cli.py                         # `plexavo scan ...` entry point
+├── __main__.py                      # lets `python -m plexavo` run the CLI
 ├── checks/
 │   ├── iam.py                       # IAM-01 to IAM-06 (privilege escalation)
 │   ├── iam_hygiene.py                # IAM-07 to IAM-14 (hygiene, cross-account trust)

{plexavo-0.2.0 → plexavo-0.2.2}/plexavo.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 plexavo/__init__.py
+plexavo/__main__.py
 plexavo/auth.py
 plexavo/aws_profile_setup.py
 plexavo/cli.py
@@ -34,6 +35,8 @@ plexavo/report/fonts/DejaVuSans.ttf
 plexavo/report/fonts/GEIST-FONT-LICENSE.txt
 plexavo/report/templates/report.html.j2
 tests/test_ai_narration_offline.py
+tests/test_auth_offline.py
+tests/test_cli_entrypoint.py
 tests/test_encryption_offline.py
 tests/test_iam_hygiene_offline.py
 tests/test_iam_offline.py

{plexavo-0.2.0 → plexavo-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "plexavo"
-version = "0.2.0"
+version = "0.2.2"
 description = "Open-source AWS misconfiguration scanner — runs with your own local AWS credentials, nothing sent to anyone else."
 readme = "README.md"
 license = { text = "AGPL-3.0-or-later" }

plexavo-0.2.2/tests/test_auth_offline.py

@@ -0,0 +1,91 @@
+"""Offline tests for auth.py. No real AWS calls — boto3.Session.client is
+monkeypatched to raise the errors AWS itself would raise, to prove
+get_local_session converts them into a clear RuntimeError instead of
+letting them crash the caller.
+
+Run: python test_auth_offline.py
+"""
+
+import boto3
+from botocore.exceptions import ClientError, NoCredentialsError
+from plexavo.auth import get_local_session
+
+failures = 0
+
+
+def assert_true(cond, msg):
+    global failures
+    status = "PASS" if cond else "FAIL"
+    print(f"[{status}] {msg}")
+    if not cond:
+        failures += 1
+
+
+class _RaisingClient:
+    def __init__(self, exc):
+        self._exc = exc
+
+    def get_caller_identity(self):
+        raise self._exc
+
+
+def _patch_client(monkeypatch_exc):
+    original_client = boto3.Session.client
+
+    def fake_client(self, service_name, *args, **kwargs):
+        if service_name == "sts":
+            return _RaisingClient(monkeypatch_exc)
+        return original_client(self, service_name, *args, **kwargs)
+
+    return original_client, fake_client
+
+
+# --- InvalidClientTokenId (deactivated/deleted access key) surfaces as a clear RuntimeError ---
+original_client, fake_client = _patch_client(
+    ClientError(
+        {"Error": {"Code": "InvalidClientTokenId", "Message": "The security token included in the request is invalid."}},
+        "GetCallerIdentity",
+    )
+)
+boto3.Session.region_name = property(lambda self: "us-east-1")
+boto3.Session.client = fake_client
+try:
+    raised = None
+    try:
+        # profile_name=None: boto3.Session() itself always succeeds
+        # regardless of what's in this machine's real ~/.aws config —
+        # only the (monkeypatched) sts call should fail.
+        get_local_session(profile_name=None)
+    except RuntimeError as e:
+        raised = e
+    except Exception as e:
+        raised = e
+
+    assert_true(isinstance(raised, RuntimeError), "ClientError (InvalidClientTokenId) is converted to RuntimeError, not left to crash")
+    assert_true(raised is not None and "InvalidClientTokenId" in str(raised), "RuntimeError message names the AWS error code")
+finally:
+    boto3.Session.client = original_client
+
+
+# --- NoCredentialsError still produces the pre-existing clear message ---
+original_client, fake_client = _patch_client(NoCredentialsError())
+boto3.Session.client = fake_client
+try:
+    raised = None
+    try:
+        get_local_session(profile_name=None)
+    except RuntimeError as e:
+        raised = e
+    except Exception as e:
+        raised = e
+
+    assert_true(isinstance(raised, RuntimeError), "NoCredentialsError still converts to RuntimeError (regression check)")
+    assert_true(raised is not None and "No AWS credentials found" in str(raised), "NoCredentialsError message unchanged")
+finally:
+    boto3.Session.client = original_client
+    del boto3.Session.region_name
+
+
+print(f"\n{'ALL PASSED' if failures == 0 else f'{failures} FAILURE(S)'}")
+import sys
+sys.exit(1 if failures else 0)

plexavo-0.2.2/tests/test_cli_entrypoint.py

@@ -0,0 +1,50 @@
+"""Checks that `python -m plexavo` works and is equivalent to the installed
+`plexavo` command / `python -m plexavo.cli`.
+
+This is the Windows install path (README Quick start): install with pip, run
+via `py -m plexavo` instead of the Smart-App-Control-blocked `plexavo.exe`
+launcher. If the `plexavo/__main__.py` shim regresses, that path breaks.
+
+Run: python test_cli_entrypoint.py
+"""
+
+import subprocess
+import sys
+
+failures = 0
+
+
+def assert_true(cond, msg):
+    global failures
+    status = "PASS" if cond else "FAIL"
+    print(f"[{status}] {msg}")
+    if not cond:
+        failures += 1
+
+
+def run(*args):
+    return subprocess.run(
+        [sys.executable, *args],
+        capture_output=True,
+        text=True,
+    )
+
+
+print("=== python -m plexavo --version ===")
+mod = run("-m", "plexavo", "--version")
+assert_true(mod.returncode == 0, f"exits 0 (got {mod.returncode}, stderr: {mod.stderr!r})")
+assert_true("plexavo" in (mod.stdout + mod.stderr).lower(), "prints the version string")
+
+print("\n=== equivalent to python -m plexavo.cli ===")
+cli = run("-m", "plexavo.cli", "--version")
+assert_true(mod.stdout == cli.stdout, f"same --version output ({mod.stdout!r} vs {cli.stdout!r})")
+
+print("\n=== python -m plexavo --help mentions the scan subcommand ===")
+helptext = run("-m", "plexavo", "--help")
+assert_true(helptext.returncode == 0, f"--help exits 0 (got {helptext.returncode})")
+assert_true("scan" in helptext.stdout, "help lists the scan subcommand")
+assert_true("usage: plexavo" in helptext.stdout,
+            "usage line shows 'plexavo', not '__main__.py'")
+
+print(f"\n{'ALL PASSED' if failures == 0 else f'{failures} FAILURE(S)'}")
+sys.exit(1 if failures else 0)