Metadata-Version: 2.4
Name: showmyenv
Version: 1.0.1
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
