Metadata-Version: 2.4
Name: sympath
Version: 0.2.0
Summary: Universal PATH manager and tool version switcher — one folder, full control
Author-email: Srimoneyshankar Ajith <sidhunair280@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/moneytosms/sympath
Project-URL: Repository, https://github.com/moneytosms/sympath
Project-URL: Bug Tracker, https://github.com/moneytosms/sympath/issues
Keywords: symlink,path,cli,developer-tools,environment,version-manager,path-manager
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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 :: System :: Systems Administration
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# sympath

**Universal PATH manager and tool version switcher.**

One directory in PATH. All your tools linked there. Switch active versions instantly.
No downloads — sympath links what you already have installed.

```
pip install sympath
```

> **Windows:** Symlinks require Developer Mode or Administrator. Use `sympath link --shim` as a no-admin alternative (creates a `.cmd` wrapper).

---

## The Problem

- PATH has 30+ entries, thousands of characters long
- Package managers add their own dirs and fight each other
- No easy way to switch between Python 3.12 and 3.13
- New machine setup means rebuilding PATH from scratch
- Windows users hit the 260-char PATH limit

sympath solves all of this. One managed folder. One PATH entry. Full control.

---

## Quick Start

```bash
# 1. Register a folder to hold your symlinks
sympath add-folder tools C:\tools\bin        # Windows
sympath add-folder tools /home/user/.local/bin  # Linux/macOS

# 2. Run doctor to get the exact PATH snippet for your shell
sympath doctor

# 3. Add that snippet to your shell config (shown by doctor)

# 4. Start linking tools
sympath link "C:\Python313\python.exe"
sympath link "C:\Neovim\bin\nvim.exe" --name vim.exe

# 5. See what you have
sympath list

# 6. Audit your current PATH for waste
sympath audit
```

---

## Commands

### Diagnostics

#### `sympath info`
Show config file location, default folder, registered folders with link counts, and versioned tools.

#### `sympath doctor`
Detect your shell, check if managed folders are in PATH, and print the exact snippet to paste into your shell config.

```
Shell: powershell
Managed folders:
  tools  ✗ NOT in PATH  →  C:\tools\bin

Add to $PROFILE:
  $env:PATH = "C:\tools\bin;" + $env:PATH
```

#### `sympath audit [--json]`
Scan every directory in your live PATH. Reports duplicates, broken dirs, empty dirs, and total executable count.

```
PATH entries: 34
  broken:     3
  duplicates: 5
  empty:      8
  total executables exposed: 189

  C:\Windows\system32  (142 exe)
  C:\tools\bin  (31 exe)  [managed]
  C:\Python312  (DUPLICATE)
  C:\OldApp\bin  (BROKEN)
```

---

### Folder Management

#### `sympath add-folder <name> <path> [--force]`
Register a directory to hold symlinks. First folder registered becomes the default.

```bash
sympath add-folder tools C:\tools\bin
sympath add-folder dev   C:\dev\bin
```

#### `sympath remove-folder <name>`
Unregister a folder. Disk contents are NOT deleted.

#### `sympath list-folders`
List all registered folders and which is the default.

#### `sympath set-default <name>`
Change which folder is used when `--folder` is omitted.

---

### PATH Migration

#### `sympath migrate-path <dir> [--dry-run] [--confirm] [--folder NAME] [--force]`
Link all executables from an existing PATH directory into your managed folder.
Always preview with `--dry-run` first.

```bash
sympath migrate-path "C:\MinGW\bin" --dry-run
sympath migrate-path "C:\MinGW\bin" --confirm
```

---

### Link Management

#### `sympath link <target> [--name ALIAS] [--folder NAME] [--force] [--dry-run] [--shim]`
Create a symlink to an executable.

```bash
sympath link "C:\Neovim\bin\nvim.exe"
sympath link "C:\Neovim\bin\nvim.exe" --name vim.exe
sympath link "C:\Python313\python.exe" --shim    # Windows: no admin needed
```

`--shim` creates a `.cmd` wrapper (Windows) or shell script (POSIX) instead of a symlink. Callable without extension on Windows.

#### `sympath link-folder <path> [--folder NAME] [--force] [--dry-run]`
Link every executable found in a directory.

```bash
sympath link-folder "C:\Program Files\LLVM\bin"
sympath link-folder /usr/local/go/bin --folder dev
```

#### `sympath remove <name> [--folder NAME]`
Remove a managed symlink.

#### `sympath list [--folder NAME] [--json]`
List all symlinks with targets. Broken links flagged.

#### `sympath repair [--folder NAME] [--delete] [--dry-run] [--json]`
Find broken symlinks. Use `--delete` to remove them.

---

### Version Switching

Track multiple installed versions of any tool and switch between them instantly.
sympath does **not** download anything — it links what you already have.

#### `sympath register <tool> <path> --version <ver> [--folder NAME] [--force]`
Register a named version of any tool. First version registered is automatically activated.

```bash
sympath register python C:\Python313\python.exe --version 3.13
sympath register python C:\Python312\python.exe --version 3.12
sympath register node   C:\nvm\v20\node.exe     --version v20
```

#### `sympath use <tool> <version> [--folder NAME]`
Switch the active version (swaps the symlink instantly).

```bash
sympath use python 3.12
sympath use node v20
```

#### `sympath which <tool>`
Show active and all registered versions.

```
Tool: python
Active: 3.13 *
Versions:
  * 3.13  →  C:\Python313\python.exe
    3.12  →  C:\Python312\python.exe
```

#### `sympath versions`
List all tools that have registered versions.

---

### Environment Profiles

Profiles are named snapshots of active tool versions. Switch your entire tool environment in one command.

#### `sympath profile create <name> [--force]`
Save current active versions as a named profile.

```bash
sympath profile create dev
sympath profile create ml
```

#### `sympath profile switch <name>`
Activate a saved profile (swaps all version symlinks).

```bash
sympath profile switch ml
```

#### `sympath profile list`
List all saved profiles.

---

### Export / Import

Portable setup — replicate your tool registry on a new machine or share with teammates.

#### `sympath export [--file <path>]`
Export all folders, versions, and profiles to JSON.

```bash
sympath export --file tools.json
```

#### `sympath import <file> [--force]`
Import from a previously exported file.

```bash
sympath import tools.json
```

---

## Configuration

State is stored in `~/.sympath.json`:

```json
{
  "default": "tools",
  "folders": {
    "tools": "C:\\tools\\bin",
    "dev":   "C:\\dev\\bin"
  },
  "versions": {
    "python": {
      "active": "3.13",
      "entries": {
        "3.13": "C:\\Python313\\python.exe",
        "3.12": "C:\\Python312\\python.exe"
      }
    }
  },
  "profiles": {
    "dev": { "python": "3.13" },
    "ml":  { "python": "3.12" }
  }
}
```

---

## Cross-Platform

| Feature | Windows | Linux | macOS |
|---|---|---|---|
| Symlinks | Requires Developer Mode or Admin | ✓ | ✓ |
| Shims (`--shim`) | ✓ `.cmd` wrapper | ✓ shell script | ✓ shell script |
| Executable detection | `.exe .cmd .bat .ps1 .sh` | executable bit | executable bit |
| PATH separator | `;` | `:` | `:` |
| Config location | `%USERPROFILE%\.sympath.json` | `~/.sympath.json` | `~/.sympath.json` |

---

## Development

```powershell
uv sync --dev          # install deps
uv run pytest          # run tests
uv build               # build dist/
.\dev.ps1 test-cov     # tests with coverage
```

---

## Roadmap

- `sympath tui` — interactive dashboard (browse, switch versions, repair)
- `.sympathrc` — per-project profile auto-activation via shell hook
- `sympath shell hook` — generate cd hook for auto-profile switching

---

## License

MIT — [github.com/moneytosms/sympath](https://github.com/moneytosms/sympath)
