showmyenv 1.0.0__tar.gz

showmyenv-1.0.0/.claude/settings.local.json

@@ -0,0 +1,49 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m venv .venv)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(/usr/bin/python3 -m venv .venv)",
+      "Read(//opt/homebrew/bin/**)",
+      "Read(//usr/local/bin/**)",
+      "Bash(/opt/homebrew/bin/python3.13 -m venv .venv)",
+      "Bash(/opt/homebrew/bin/python3.11 -m venv .venv)",
+      "Bash(/opt/homebrew/bin/python3 -m venv .venv)",
+      "Bash(python3 -c \"import ensurepip; print\\(ensurepip.__version__\\)\")",
+      "Bash(/opt/homebrew/bin/python3 -m venv .venv --without-pip)",
+      "Bash(curl -sS https://bootstrap.pypa.io/get-pip.py)",
+      "Bash(.venv/bin/python3)",
+      "Bash(/opt/homebrew/bin/python3.11 --version)",
+      "Bash(/opt/homebrew/bin/python3.11 -c \"import ensurepip\")",
+      "Bash(/opt/homebrew/bin/python3.11 -m venv .venv --without-pip)",
+      "Bash(.venv/bin/python3.11 -m ensurepip)",
+      "Bash(/opt/homebrew/bin/python3.11 *)",
+      "Bash(.venv/bin/python3.11 -c \"import sys; sys.path.insert\\(0, '/opt/homebrew/lib/python3.11/site-packages'\\); import pip; print\\(pip.__version__\\)\")",
+      "Bash(/opt/homebrew/Cellar/python@3.13/3.13.13_1/bin/python3.13 --version)",
+      "Bash(/opt/homebrew/Cellar/python@3.13/3.13.13_1/bin/python3.13 -m ensurepip)",
+      "Bash(/opt/homebrew/Cellar/python@3.13/3.13.13_1/bin/pip3.13 *)",
+      "Bash(/opt/homebrew/Cellar/python@3.13/3.13.13_1/bin/python3.13 -m venv .venv --without-pip)",
+      "Bash(.venv/bin/python3.13 -c \"import sys; print\\(sys.version\\)\")",
+      "Bash(/usr/bin/python3 --version)",
+      "Bash(/usr/bin/python3 -m pip --version)",
+      "Bash(.venv/bin/pip --version)",
+      "Bash(.venv/bin/ruff format *)",
+      "Bash(.venv/bin/pytest tests/ -x -q)",
+      "Bash(.venv/bin/ruff check *)",
+      "Bash(.venv/bin/mypy src/showmyenv)",
+      "Bash(.venv/bin/pytest tests/ -q)",
+      "Bash(.venv/bin/showmyenv --version)",
+      "Bash(.venv/bin/showmyenv which *)",
+      "Bash(.venv/bin/showmyenv scan *)",
+      "Bash(.venv/bin/showmyenv quick *)",
+      "Bash(.venv/bin/showmyenv docker *)",
+      "Bash(.venv/bin/showmyenv report *)",
+      "Read(//tmp/**)",
+      "Bash(.venv/bin/pytest *)",
+      "Bash(git -C /Users/kshitizyadav/Projects/showmyenv status)",
+      "Bash(git -C /Users/kshitizyadav/Projects/showmyenv log --oneline -5)",
+      "Bash(git *)",
+      "Bash(.venv/bin/python -m build)"
+    ]
+  }
+}

showmyenv-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.DS_Store
+*.json.snapshot
+showmyenv_snapshot*.json
+/tmp/

showmyenv-1.0.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+Guidance for AI agents and contributors working in this repository.
+
+## What this is
+
+ShowMyEnv is a read-only environment **diagnostic** CLI. It does not just list installed versions — it explains what is *actually being used*, what is *influencing* it, what is *conflicting*, and what to *fix*. Keep that mission in mind: a change that only adds version reporting is low value; a change that explains behavior is on-mission.
+
+## Two rules that override everything
+
+1. **Read-only by contract.** Never write env vars, modify PATH, install/remove packages, or start/stop containers. We inspect, we never mutate. Any PR that mutates the host environment is wrong.
+2. **Collect once, render many.** Collectors return typed dataclasses (`models.py`); renderers turn those into console/JSON/Markdown/HTML. Collectors **must not print**, and renderers **must not collect**. If you find yourself parsing text in a renderer or formatting strings in a collector, stop.
+
+## Architecture
+
+```
+collectors/  → return dataclasses        (gather facts, never print)
+models.py    → the data contract          (serializable; bump schema_version on breaking change)
+diagnostics/ → pure functions over models (health score, doctor, root-cause rules)
+report/      → snapshot, compare, formatters (json/markdown/html)
+render/      → Rich console output
+cli.py       → Typer app; wires commands to collectors → diagnostics → renderer
+context.py   → ScanContext: injects PATH/env/which-resolver and caches results within one run
+```
+
+The root serialized object is `Scan` in `models.py`. Everything (`scan`, `report`, `snapshot`, `--json`) flows from it.
+
+`Severity` (INFO/LOW/MEDIUM/HIGH/CRITICAL) and `Finding` are the shared vocabulary. Every issue any module detects is a `Finding`. The health score deducts points by `Finding`, so each deduction is explainable.
+
+## Commands
+
+```bash
+# Setup (uses a venv; never install into the user's global env)
+python -m venv .venv && . .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+# Run during development
+python -m showmyenv scan
+python -m showmyenv which
+python -m showmyenv health
+
+# Quality gates — run all three before considering work done
+ruff format .        # format
+ruff check . --fix   # lint
+mypy src/showmyenv   # type check (strict on models + collectors)
+pytest               # tests
+pytest tests/collectors/test_path_analyzer.py -k shadow   # focused run
+```
+
+If a task touches collection or models, run `mypy` — the model layer is a contract and must stay typed.
+
+## Dependency policy (strict)
+
+Runtime dependencies are limited to **`typer`, `rich`, `psutil`**. Do not add others. Do not import the docker SDK, boto3, or cloud SDKs — shell out to the user's own `docker` / `aws` / `az` / `gcloud` / language binaries via `subprocess`. Shelling out is more truthful (it reflects real resolution) and keeps the tool from breaking in the broken environments it exists to diagnose. New dev-only deps are fine in the `[dev]` extra.
+
+## Cross-platform rules
+
+- Use `pathlib.Path`, `os.pathsep`, and `shutil.which` (it handles Windows PATHEXT). Never hardcode `C:\...` or `/usr/local/...` — platform-specific known locations live in one table per collector.
+- "Tool not found", "daemon not running", and "permission denied" are **normal reportable states**, not exceptions. Return a model with an INFO/relevant `Finding`; never crash a scan because one collector couldn't run.
+- Default scan is **offline and fast**. Anything needing the network (e.g. outdated-package checks) is gated behind `--check-updates`.
+
+## Security
+
+- Redact by default in every report format. Detect secret-shaped env vars (tokens, keys) and never echo their values.
+- Never dump the full environment — only the curated allowlist in `collectors/env_vars.py`.
+- Report credential *sources* (env / file / SSO), never credential *values*.
+
+## Recipe: add a new runtime collector
+
+This is the most common extension. Follow the existing `collectors/runtimes/python.py` as the reference.
+
+1. Create `collectors/runtimes/<name>.py` implementing the `RuntimeCollector` protocol from `runtimes/base.py`. It receives a `ScanContext` and returns a `RuntimeInfo`.
+2. Populate at minimum: `active_version`, `active_path` (use `ctx.which("<bin>")`), `installed_versions` (best-effort), and any `extra` fields (e.g. version-manager root). Mark discovery confidence honestly.
+3. Emit `Finding`s for misconfigurations you can detect (e.g. resolved binary disagrees with the relevant `*_HOME` env var).
+4. Register the collector in the runtime registry in `collectors/runtimes/__init__.py`.
+5. Add a fixture-based test in `tests/collectors/` using a fake PATH/which resolver — do **not** depend on the host having the runtime installed.
+6. If the runtime introduces a new conflict class, add a rule in `diagnostics/conflicts.py` (operates on models only).
+
+Never read `os.environ` or call `shutil.which` directly inside a collector — go through `ScanContext` so the collector stays testable.
+
+## Recipe: add a root-cause rule
+
+Rules live in `diagnostics/root_cause.py` as `(matches(scan) -> bool, explanation, ranked_causes, fixes)`. They consume the `Scan` model and emit findings/explanations. Adding a rule must not require touching any collector. Add a test that builds a hand-crafted `Scan` and asserts the rule fires.
+
+## Schema changes
+
+`models.Scan.schema_version` is persisted in snapshots and reports. Any breaking change to the serialized shape must bump it and add a migration shim so `compare` can still read older snapshots. Update the golden fixtures in `tests/fixtures/` accordingly.
+
+## Definition of done
+
+- Collectors don't print; renderers don't collect.
+- New runtime deps? Only if it's `typer`/`rich`/`psutil` (it isn't — so no).
+- `ruff format`, `ruff check`, `mypy`, and `pytest` all pass.
+- New behavior is covered by a fixture-based test that doesn't depend on the host's real environment.
+- Nothing mutates the host environment.
+
+See `PLAN.md` for the full module breakdown, health-scoring weights, and phased roadmap (v0.1 → v0.2 → v1.0).

showmyenv-1.0.0/LICENSE

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

showmyenv-1.0.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: showmyenv
+Version: 1.0.0
+Summary: Environment diagnostic CLI: see what is actually running, what is influencing it, what conflicts, and how to fix it.
+Project-URL: Homepage, https://github.com/kshitizyadav/showmyenv
+Project-URL: Repository, https://github.com/kshitizyadav/showmyenv
+Project-URL: Bug Tracker, https://github.com/kshitizyadav/showmyenv/issues
+Author-email: Kshitiz Yadav <kshitizyadav6@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,developer-tools,devtools,diagnostic,environment,path,runtime
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-psutil>=5.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# showmyenv
+
+> Other tools tell you what's installed. **showmyenv** tells you what's *actually running*, what's *influencing* it, what's *conflicting* with it, and what to *fix*.
+
+A read-only environment diagnostic CLI for developers. It inspects your shell environment and explains it — no mutations, no side effects.
+
+## Installation
+
+```bash
+pip install showmyenv
+# or
+pipx install showmyenv
+```
+
+Requires Python 3.9 or later. Runtime dependencies: `typer`, `rich`, `psutil`.
+
+## Quick start
+
+```bash
+showmyenv          # full scan (same as showmyenv scan)
+showmyenv quick    # fast scan, skips Docker/Cloud/IDE discovery
+showmyenv health   # health score with grade and per-category breakdown
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `showmyenv scan` | Full environment scan |
+| `showmyenv quick` | Fast scan (runtimes, PATH, ports only) |
+| `showmyenv health` | Health score and all findings |
+| `showmyenv which` | Show how each known command resolves |
+| `showmyenv ports` | Listening ports with likely service names |
+| `showmyenv docker` | Docker containers, images, disk usage |
+| `showmyenv doctor` | Check project manifest requirements against active runtimes |
+| `showmyenv snapshot` | Save a snapshot to JSON |
+| `showmyenv compare A B` | Diff two snapshot files |
+| `showmyenv report` | Generate a report (`--format json\|markdown\|html`) |
+
+All commands accept `--json` for machine-readable output.
+
+## What it checks
+
+### Runtimes
+
+Detects active versions and install paths for Python, Node.js, Java, Go, Rust, .NET, Ruby, and PHP. For each runtime it reports:
+
+- The resolved executable and its version
+- Installed versions from version managers (pyenv, nvm, rbenv, rustup, sdkman)
+- Misconfigurations — for example, `VIRTUAL_ENV` set but the resolved Python living outside it, or `JAVA_HOME` pointing somewhere different from the `java` on PATH
+
+### PATH analysis
+
+- Duplicate entries
+- Broken entries (directory does not exist)
+- **Shadowing** — when an older version of a tool appears earlier in PATH than a newer one, this is flagged HIGH and explained
+
+### Project Doctor (`showmyenv doctor`)
+
+Reads manifest files in the current directory and compares their declared runtime requirements against what is actually active:
+
+```
+Runtime  Required  Active  Status  Source
+python   >=3.11    3.9.6   FAIL    pyproject.toml
+node     ^18       20.11   PASS    package.json
+```
+
+Supported manifests: `pyproject.toml`, `package.json`, `go.mod`, `pom.xml`, `build.gradle`, `Dockerfile`, `.tool-versions`, `.nvmrc`, `.python-version`, `rust-toolchain.toml`, `Gemfile`, `composer.json`, `global.json`, and more.
+
+### Conflict detection
+
+Pure analysis over collected data — no extra system calls:
+
+- Virtualenv present but inactive
+- Multiple JS package manager lockfiles (`package-lock.json` + `yarn.lock` + `pnpm-lock.yaml`)
+- Multiple Python version managers active simultaneously
+- `packageManager` field in `package.json` disagrees with the resolved package manager
+
+### Root cause engine
+
+When known problem patterns are detected, showmyenv explains them with ranked causes and actionable fixes. Current rules:
+
+- **Package installed but won't import** — fires on interpreter/venv mismatches
+- **Older tool shadows newer** — fires on HIGH-severity PATH shadows
+- **Wrong Java version** — fires on JAVA_HOME mismatches or failed doctor checks
+- **Node version mismatch** — fires on failed doctor checks or lockfile conflicts
+- **Docker reclaimable space** — fires when Docker has significant space to reclaim
+
+### Docker
+
+Shells out to the local `docker` binary (no SDK dependency). Reports containers, images, disk usage, and reclaimable space. Degrades gracefully when Docker is not installed or the daemon is not running.
+
+### Cloud environment
+
+Detects active AWS, Azure, and GCP configuration by shelling out to `aws`, `az`, and `gcloud`. Reports the active account/project/subscription and where credentials come from (environment variable, config file, or SSO). **Credential values are never echoed.**
+
+### IDE discovery
+
+Finds installed editors via well-known application paths and CLI shims: VS Code, Cursor, Windsurf, IntelliJ IDEA, PyCharm, WebStorm, Vim, Neovim, Emacs, Zed.
+
+### Health score
+
+A weighted score from 0–100 with a letter grade (A–F):
+
+| Category | Weight |
+|---|---|
+| Runtime Configuration | 25% |
+| PATH Integrity | 20% |
+| Dependency Health | 20% |
+| Security Checks | 15% |
+| Environment Variables | 10% |
+| Docker Health | 10% |
+
+Every point deducted traces back to a specific finding, so the score is always explainable. Categories that don't apply (e.g. no Docker) are marked N/A and excluded from the weighted average.
+
+### Snapshots and comparison
+
+```bash
+showmyenv snapshot -o before.json
+# ... make changes ...
+showmyenv snapshot -o after.json
+showmyenv compare before.json after.json
+```
+
+The diff shows runtime version changes, new/resolved findings, health score delta, and PATH entry changes.
+
+### Reports
+
+```bash
+showmyenv report --format json     > report.json
+showmyenv report --format markdown > report.md
+showmyenv report --format html     -o report.html
+```
+
+The HTML report is a single self-contained file with inline CSS — suitable for attaching to a ticket or sharing with a teammate.
+
+## Security
+
+- **Read-only by design.** showmyenv never writes environment variables, modifies PATH, installs packages, or starts/stops services.
+- **Secret redaction.** Environment variables matching secret-shaped patterns (`API_KEY`, `SECRET`, `TOKEN`, `PASSWORD`, etc.) are detected and their values are replaced with `[redacted]` in all output formats.
+- **No full environment dump.** Only a curated allowlist of meaningful variables is collected and shown.
+- **Credential sources, not values.** The cloud collector reports *where* credentials come from (env var / config file / SSO), never the credential itself.
+
+## Environment variables understood
+
+showmyenv reads but never modifies: `JAVA_HOME`, `PYTHONPATH`, `VIRTUAL_ENV`, `CONDA_DEFAULT_ENV`, `NODE_PATH`, `NPM_CONFIG_PREFIX`, `GOROOT`, `GOPATH`, `GOBIN`, `CARGO_HOME`, `RUSTUP_HOME`, `GEM_HOME`, `RBENV_ROOT`, `PYENV_ROOT`, `NVM_DIR`, `AWS_PROFILE`, `AWS_REGION`, `GOOGLE_CLOUD_PROJECT`, `AZURE_SUBSCRIPTION_ID`, `DOCKER_HOST`, `KUBECONFIG`, `PATH`, `SHELL`, `LANG`, `HOME`, `USER`.
+
+## Global flags
+
+```
+--json        Output as JSON (any command)
+--no-color    Disable color output
+--check-updates  Check for outdated packages (requires network, scan only)
+--version     Print version and exit
+```
+
+## Development
+
+```bash
+git clone https://github.com/kshitizyadav/showmyenv
+cd showmyenv
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Run during development
+showmyenv scan
+showmyenv health
+showmyenv doctor
+
+# Quality gates (run before submitting a PR)
+ruff format .
+ruff check . --fix
+mypy src/showmyenv
+pytest
+```
+
+### Adding a new runtime collector
+
+1. Create `src/showmyenv/collectors/runtimes/<name>.py` following the pattern in `python.py` or `go.py`. The collector receives a `ScanContext` and returns a `RuntimeInfo`.
+2. Register it in `src/showmyenv/collectors/runtimes/__init__.py`.
+3. Add a fixture-based test in `tests/collectors/` using a fake binary — do not depend on the host having the runtime installed.
+
+See `CLAUDE.md` for the full contributor guide.
+
+## License
+
+MIT