sympath 0.1.0__tar.gz

sympath-0.1.0/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: sympath
+Version: 0.1.0
+Summary: A powerful symlink-based path manager for developers
+License: MIT
+Keywords: symlink,path,cli,developer-tools,environment
+Classifier: Development Status :: 3 - Alpha
+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 :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 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
+
+### From source (editable / development)
+
+```bash
+git clone https://github.com/your-user/sympath.git
+cd sympath
+pip install -e .
+```
+
+### Run without installing
+
+```bash
+python -m sympath --help
+```
+
+> **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

sympath-0.1.0/README.md

@@ -0,0 +1,272 @@
+# 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
+
+### From source (editable / development)
+
+```bash
+git clone https://github.com/your-user/sympath.git
+cd sympath
+pip install -e .
+```
+
+### Run without installing
+
+```bash
+python -m sympath --help
+```
+
+> **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

sympath-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sympath"
+version = "0.1.0"
+description = "A powerful symlink-based path manager for developers"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["symlink", "path", "cli", "developer-tools", "environment"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+]
+
+[project.scripts]
+sympath = "sympath.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["sympath*"]

sympath-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sympath-0.1.0/sympath/__init__.py

@@ -0,0 +1,3 @@
+"""Sympath — a powerful symlink-based path manager."""
+
+__version__ = "0.1.0"

sympath-0.1.0/sympath/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running sympath as ``python -m sympath``."""
+
+from sympath.cli import main
+
+main()