portal-handler 0.1.0

# portal.nvim

[![GitHub](https://img.shields.io/github/license/Yaici-Yacine/portal.nvim)](https://github.com/Yaici-Yacine/portal.nvim/blob/main/LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/Yaici-Yacine/portal.nvim)](https://github.com/Yaici-Yacine/portal.nvim/releases)

Ouvre des fichiers dans Neovim depuis n'importe où via le schéma URI `nvim://` — comme `vscode://` pour VS Code.

---

## Démo

```
Browser / Terminal / LocatorJS
        │
   nvim://open?file=/home/user/projet/src/main.rs&line=42
        │
┌───────▼────────────────┐
│   portal-handler        │  ← binaire Rust (~/.cargo/bin)
│   (détecte le socket)   │    priorité: $NVIM → XDG_RUNTIME_DIR → /tmp
└───────┬────────────────┘
        │ RPC msgpack (nvim-rs)
        ▼
┌────────────────────────┐
│   Neovim (instance      │  ← ouvre le fichier, positionne le curseur
│   active)               │
└────────────────────────┘
```

---

## Fonctionnalités

- Supporte `nvim://open?file=PATH&line=N&col=N` (format natif)
- Supporte `nvim://file/PATH:LINE:COL` (format LocatorJS)
- Enregistrement OS automatique (Linux `.desktop`, macOS `.app`, Windows registre)
- Détection automatique du socket Neovim actif
- Sécurité : validation des chemins, rejet des métacaractères

---

## Prérequis

- Neovim >= 0.9
- [Rust](https://rustup.rs)

---

## Installation

### lazy.nvim

```lua
{
  "Yaici-Yacine/portal.nvim",
  build = function() vim.fn.system("cargo install portal-handler") end,
  config = function()
    require("portal").setup({
      auto_server    = true,
      notify_on_open = true,
    })
  end,
}
```

Après la première installation, enregistrer le schéma URI dans le système :

```vim
:PortalInstall
```

### Installation manuelle

```bash
cargo install portal-handler
```

Puis cloner le dépôt et ajouter le chemin au `rtp` Neovim :

```lua
vim.opt.rtp:prepend("/chemin/vers/portal.nvim")
require("portal").setup()
```

---

## Commandes

| Commande | Description |
|---|---|
| `:PortalOpen <uri>` | Tester une URI directement dans Neovim |
| `:PortalInstall` | Enregistrer `nvim://` dans le système (Linux/macOS/Windows) |
| `:PortalUninstall` | Désinstaller le handler |
| `:PortalStatus` | Afficher le socket actif + statut du handler |
| `:PortalCopy` | Copier l'URI du fichier et de la ligne courante |
| `:PortalBuild` | Recompiler le binaire Rust manuellement |

---

## URIs supportées

```
nvim://open?file=/path/to/file.lua
nvim://open?file=/path/to/file.lua&line=42&col=7
nvim://open?file=/path/to/file.lua&split=vertical
nvim://open?file=/path/to/file.lua&tab=true
nvim://file//path/to/file.lua:42:7    ← format LocatorJS
```

---

## Intégration LocatorJS

[LocatorJS](https://www.locatorjs.com) est un outil qui permet de cliquer sur un composant dans le navigateur pour ouvrir directement le fichier source dans l'éditeur.

Dans les paramètres de LocatorJS, sélectionner **"Neovim"** ou définir un lien personnalisé :

```
nvim://file/${projectPath}${filePath}:${line}:${column}
```

> Requiert que `:PortalInstall` ait été exécuté au préalable.

---

## Configuration

```lua
require("portal").setup({
  open_cmd       = "edit",   -- "edit" | "split" | "vsplit" | "tabedit"
  focus_existing = true,     -- focus une fenêtre existante si le fichier est déjà ouvert
  allowed_dirs   = {},       -- whitelist de dossiers (vide = tout autorisé)
  deny_modeline  = true,     -- désactiver modeline pour les fichiers ouverts via URI
  notify_on_open = true,     -- notification lors de l'ouverture
  auto_server    = false,    -- démarrer serverstart() automatiquement
})
```

---

## Comment ça marche

```
Browser / Terminal / LocatorJS
        │
   nvim://file//path/to/file.lua:42:7
        │
┌───────▼────────────────┐
│   portal-handler        │  ← binaire Rust (~/.cargo/bin)
│   (détecte le socket)   │    priorité: $NVIM → XDG_RUNTIME_DIR → /tmp
└───────┬────────────────┘
        │ RPC msgpack (nvim-rs)
        ▼
┌────────────────────────┐
│   Neovim (instance      │  ← ouvre le fichier, positionne le curseur
│   active)               │
└────────────────────────┘
```

Le binaire `portal-handler` est invoqué par le système d'exploitation dès qu'une URI `nvim://` est cliquée. Il localise le socket Unix de l'instance Neovim active, puis envoie un appel RPC msgpack pour ouvrir le fichier à la position demandée.

---

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## Licence

MIT