feat: add alias file generation and management for shell hooks
Release / release (push) Successful in 49s

- **Aliases**: Generate shell alias files (`aliases.sh` for bash/zsh, `netssh.fish` for fish) from cached hosts. Regenerate on each shell startup and cache refresh to keep aliases updated.
- **Hooks**: Extend shell hook functionality to include alias file support. Install and uninstall commands updated for bash, zsh, and fish.
- **Tests**: Add unit tests to verify alias file generation, path resolution, and idempotent hook installation.
- **Docs**: Update README with instructions for alias file usage, installation, and relation to hooks.
This commit is contained in:
Sebastian Unterschütz
2026-05-27 23:08:30 +02:00
parent 7c902cab3a
commit fa646f25a6
5 changed files with 450 additions and 58 deletions
+51 -15
View File
@@ -329,7 +329,12 @@ Completions are served from the local cache — no network request on every `<Ta
## Shell Hook
The shell hook runs `netssh shell-init` at the start of every new shell session. It checks whether the cache is older than 24 hours and, if so, starts a background refresh. The check reads a single small file and adds no measurable delay to your shell startup.
`netssh hook install` sets up two things in your shell profile:
1. **`netssh shell-init`** — runs on every new shell session. It regenerates the alias file from the current cache so your aliases are always up to date, and starts a background cache refresh if the last full refresh was more than 24 hours ago.
2. **A `source` line** (bash/zsh only) — loads the generated alias file so shortcuts like `web01` work immediately in every new shell. Fish uses `conf.d/` auto-sourcing instead, so no explicit source line is needed.
The alias file is also generated immediately during `hook install`, so aliases are available as soon as you reload your profile — no `cache refresh` needed first (though the cache must not be empty).
### Install
@@ -340,21 +345,38 @@ netssh hook install --shell zsh
netssh hook install --shell fish
```
This appends exactly one line to your shell profile:
Example output:
```sh
```
Hook installed → /home/user/.bashrc
Reload with: source /home/user/.bashrc
42 aliases written to /home/user/.cache/netssh/aliases.sh
```
What gets written to the profile:
**bash / zsh** (`~/.bashrc` or `~/.zshrc`):
```bash
netssh shell-init # netssh cache auto-refresh
source ~/.cache/netssh/aliases.sh 2>/dev/null # netssh aliases
```
**fish** (`~/.config/fish/config.fish`):
```fish
netssh shell-init # netssh cache auto-refresh
```
| Shell | Profile file |
|-------|-------------|
| bash | `~/.bashrc` |
| zsh | `~/.zshrc` |
| fish | `~/.config/fish/config.fish` |
Fish alias file (`~/.config/fish/conf.d/netssh.fish`) is written automatically and sourced by fish on every shell start without any profile changes.
The install is idempotent — running it again does nothing if the hook is already present.
| Shell | Profile file | Alias file |
|-------|-------------|------------|
| bash | `~/.bashrc` | `~/.cache/netssh/aliases.sh` |
| zsh | `~/.zshrc` | `~/.cache/netssh/aliases.sh` |
| fish | `~/.config/fish/config.fish` | `~/.config/fish/conf.d/netssh.fish` |
Reload your profile after installation:
The install is idempotent — running it again changes nothing if the lines are already present.
Reload your profile after installation to activate immediately:
```sh
source ~/.bashrc # bash
@@ -362,6 +384,18 @@ source ~/.zshrc # zsh
source ~/.config/fish/config.fish # fish
```
### Alias file updates
The alias file is regenerated automatically — no manual action needed:
| Event | Aliases updated |
|-------|----------------|
| New shell session (`shell-init`) | Yes — from the current local cache |
| `netssh cache refresh` | Yes — after the full refresh completes |
| Background 24h auto-refresh | Yes — after the background refresh completes |
Aliases for newly added hosts appear in the next shell session after a `cache refresh` has run.
### Uninstall
```sh
@@ -369,16 +403,18 @@ netssh hook uninstall # auto-detects $SHELL
netssh hook uninstall --shell zsh
```
Removes the `netssh shell-init` line from the profile and collapses any blank lines left behind.
Removes both the `netssh shell-init` line and the `source aliases.sh` line from the profile. The alias files (`aliases.sh`, `netssh.fish`) are left on disk — delete them manually if desired.
### How it differs from the connect-time trigger
### Relation to the connect-time auto-refresh
The shell hook and the connect-time trigger (which fires on each `netssh` invocation) are independent but complementary:
| Trigger | When it fires |
|---------|--------------|
| Connect / TUI start | On the next SSH command or `netssh` TUI after 24 h |
| Shell hook | On the first new shell session after 24 h |
| SSH connect / TUI start | On the next `netssh` call after 24 h have elapsed |
| Shell hook (`shell-init`) | On the first new shell session after 24 h have elapsed |
Both triggers are non-blocking: the refresh runs in the background and your SSH connection (or prompt) is not delayed. You can install both — they share the same `~/.cache/netssh/last_refresh` timestamp, so the background process runs at most once per 24 hours regardless of how many shells or connections you open.
Both are non-blocking the refresh runs as a background process and never delays your prompt or SSH connection. They share `~/.cache/netssh/last_refresh`, so only one background refresh runs per 24-hour window regardless of how many shells or connections are opened.
## Development