# sympath

**A powerful, cross-platform symlink-based path manager for developers.**

sympath lets you stop cluttering your system `PATH` with dozens of directories. Instead, maintain **one folder** full of symlinks that point to the real executables — and only add that single folder to `PATH`.

This is how Linux distros manage `/usr/local/bin`, and now you can do it on any OS.

---

## Why sympath?

| Problem                                 | sympath's Solution                       |
| --------------------------------------- | -------------------------------------- |
| `PATH` is thousands of characters long  | One clean directory in `PATH`          |
| Duplicate / stale `PATH` entries        | Managed symlinks you can list & repair |
| Package managers fight over `PATH`      | You decide what's exposed              |
| Hard to see what tools are available    | `sympath list` shows everything          |
| Different projects need different tools | Multiple named link folders            |

---

## Installation

```bash
pip install sympath
```

### From source (development)

```bash
git clone https://github.com/your-user/sympath.git
cd sympath
pip install -e .
```

> **Note (Windows):** Creating symlinks may require **Administrator** privileges or Developer Mode enabled.

---

## Quick Start

```bash
# 1. Register a link directory
sympath add-folder tools C:\tools\bin

# 2. Add that directory to your system PATH (once, manually)

# 3. Link individual executables
sympath link "C:\Program Files\Neovim\bin\nvim.exe"
sympath link "C:\MinGW\bin\gcc.exe"
sympath link "C:\Python313\python.exe" --name py.exe

# 4. Or link every executable in a folder at once
sympath link-folder "C:\Program Files\LLVM\bin"

# 5. See what you have
sympath list

# 6. Remove a link you no longer need
sympath remove gcc.exe

# 7. Find and report broken links
sympath repair
```

After this, running `nvim`, `gcc`, or `py` from any terminal will just work — they all resolve through `C:\tools\bin`.

---

## Commands

### `sympath add-folder <name> <path>`

Register a directory that will hold symlinks. The first folder you register automatically becomes the default.

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

### `sympath set-default <name>`

Change which registered folder is used when no `--folder` flag is given.

```bash
sympath set-default dev
```

### `sympath link <target> [options]`

Create a symlink inside the default (or specified) folder pointing to `<target>`.

| Option            | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| `--name <alias>`  | Use a custom filename for the symlink instead of the target's basename |
| `--folder <name>` | Place the link in a specific registered folder                         |
| `--force`         | Overwrite an existing symlink without prompting                        |

```bash
# Basic
sympath link "C:\Program Files\Neovim\bin\nvim.exe"

# Custom name
sympath link "C:\Program Files\Neovim\bin\nvim.exe" --name vim.exe

# Into a specific folder, overwriting if it exists
sympath link "C:\Python313\python.exe" --folder dev --force
```

### `sympath link-folder <path> [options]`

Scan a directory and create symlinks for **every executable** found inside it.

| Option            | Description              |
| ----------------- | ------------------------ |
| `--folder <name>` | Target link folder       |
| `--force`         | Overwrite existing links |

Executable detection:

- **Windows** — `.exe`, `.cmd`, `.bat`, `.ps1`, `.sh`
- **Linux / macOS** — any file with the executable permission bit

```bash
sympath link-folder "C:\Program Files\LLVM\bin"
```

### `sympath remove <name> [--folder <name>]`

Delete a managed symlink.

```bash
sympath remove gcc.exe
sympath remove gcc.exe --folder dev
```

### `sympath list [--folder <name>]`

Display all symlinks in a folder with their targets. Broken links are flagged.

```bash
sympath list
```

```
  python.exe → C:\Python313\python.exe
  gcc.exe    → C:\MinGW\bin\gcc.exe
  nvim.exe   → C:\Program Files\Neovim\bin\nvim.exe  [BROKEN]
```

### `sympath repair [--folder <name>]`

Scan for symlinks whose targets no longer exist and report them.

```bash
sympath repair
```

```
  Broken: C:\tools\bin\nvim.exe
  Broken: C:\tools\bin\python.exe
```

### Global Options

| Flag              | Description                 |
| ----------------- | --------------------------- |
| `-h`, `--help`    | Show help for any command   |
| `-v`, `--version` | Print the installed version |

```bash
sympath --help
sympath link --help
sympath --version
```

---

## Configuration

sympath stores its state in a single JSON file:

```
~/.sympath.json
```

Example contents:

```json
{
  "default": "tools",
  "folders": {
    "tools": "C:\\tools\\bin",
    "dev": "C:\\dev\\bin"
  }
}
```

| Field     | Type     | Description                                        |
| --------- | -------- | -------------------------------------------------- |
| `default` | `string` | Name of the folder used when `--folder` is omitted |
| `folders` | `object` | Map of registered name → absolute directory path   |

---

## Cross-Platform Support

| Platform    | Executable Detection                   | Notes                                            |
| ----------- | -------------------------------------- | ------------------------------------------------ |
| **Windows** | `.exe`, `.cmd`, `.bat`, `.ps1`, `.sh`  | May require admin or Developer Mode for symlinks |
| **Linux**   | Executable permission bit (`chmod +x`) | Works out of the box                             |
| **macOS**   | Executable permission bit (`chmod +x`) | Works out of the box                             |

---

## Example Workflow

```bash
# One-time setup
sympath add-folder tools C:\tools\bin
# → then add C:\tools\bin to your system PATH

# Day-to-day usage
sympath link "C:\MinGW\bin\gcc.exe"
sympath link "C:\Program Files\Neovim\bin\nvim.exe"
sympath link "C:\Python313\python.exe" --name python.exe
sympath link-folder "C:\Program Files\Git\cmd" --force

# Maintenance
sympath list
sympath repair
sympath remove gcc.exe
```

**Result:** your `PATH` stays clean with a single entry, and all your tools are one `sympath link` away.

---

## Project Structure

```
sympath/
├── pyproject.toml       # Package metadata & entry point
├── README.md            # This file
├── vision.md            # Full feature specification
└── sympath/               # Python package
    ├── __init__.py      # Package version
    ├── __main__.py      # python -m sympath support
    ├── cli.py           # Argument parsing & command dispatch
    ├── config.py        # ~/.sympath.json load / save
    ├── manager.py       # Core SymlinkManager class
    └── utils.py         # Executable detection helpers
```

---

## Roadmap

- [ ] `sympath migrate-path` — convert existing PATH dirs into managed symlinks
- [ ] `sympath scan` — discover installed tools on the system
- [ ] `sympath use <tool> <version>` — version switching
- [ ] `sympath profile <name>` — environment profiles
- [ ] Plugin system for tool-specific managers

---

## License

MIT
