Metadata-Version: 2.4
Name: proxy-path-doctor
Version: 0.5.0
Summary: A read-only CLI for diagnosing mismatched proxy configuration sources.
Author: proxy-path-doctor contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/oneAI6/proxy-doctor
Project-URL: Issues, https://github.com/oneAI6/proxy-doctor/issues
Project-URL: Changelog, https://github.com/oneAI6/proxy-doctor/blob/main/CHANGELOG.md
Keywords: proxy,network,diagnostics,windows,linux
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# proxy-path-doctor

`proxy-path-doctor` is a small, privacy-conscious, read-only CLI for diagnosing
conflicting proxy configuration sources. It collects the settings that commonly
cause confusing network failures, highlights mismatches, and produces a report
that is safe to share in an issue.

The project is currently an early MVP. It supports Windows system proxy
inspection, GNOME desktop proxy inspection on Linux, and portable checks for
proxy environment variables, DNS, and optional HTTP connectivity.

## Why this exists

Network failures are often reported as "the proxy looks correct" while several
independent settings are involved. `proxy-path-doctor` gathers those signals in
one place and redacts credentials before printing them.

The tool does not modify proxy settings, manage proxy servers, or choose a proxy
provider. Its focus is explaining which configuration path a program may be
using across Windows, Linux, environment variables, and connectivity checks.

## Install

The planned PyPI package name for the first public release is
`proxy-path-doctor`. Until then, install the current development version from
the repository:

```powershell
git clone https://github.com/oneAI6/proxy-doctor.git
cd proxy-doctor
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
```

## Usage

Inspect local settings without sending a network request:

```powershell
proxy-path-doctor
```

Include a DNS and HTTP connectivity check:

```powershell
proxy-path-doctor --check-url https://example.com
```

Check whether a local development URL is covered by `NO_PROXY`:

```powershell
proxy-path-doctor --check-url http://localhost:3000
```

Generate a JSON report for an issue:

```powershell
proxy-path-doctor --format json --output proxy-report.json
```

Any username or password embedded in a proxy URL is replaced with `***`.
Review a generated report before posting it publicly because hostnames and
proxy addresses may still describe your environment.

## Current checks

- Operating system and Python version
- Common proxy environment variables
- Windows user proxy settings
- Windows WinHTTP proxy settings
- Linux GNOME desktop proxy settings through `gsettings`
- Optional DNS resolution
- Optional HTTP `HEAD` request with a timeout
- `NO_PROXY` matching for checked URLs, including domains, ports, and IP addresses
- Actionable findings for conflicting settings and connectivity failures

## Example finding

```text
[findings]
- WARNING: Proxy environment variables are set while the Windows user proxy is
  disabled. Suggestion: Check whether your terminal, IDE, or launcher exports
  HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY intentionally.
```

## Contributing

Bug reports and focused pull requests are welcome. See
[CONTRIBUTING.md](CONTRIBUTING.md) and [docs/ROADMAP.md](docs/ROADMAP.md).
The [maintainer plan](docs/MAINTAINER_PLAN.md) describes a realistic path from
the MVP to a maintained public project.
Release notes are available in [CHANGELOG.md](CHANGELOG.md).

## License

MIT
