diff --git a/packages/server-shell-setup/README.md b/packages/server-shell-setup/README.md index c204d47f..4c93baf1 100644 --- a/packages/server-shell-setup/README.md +++ b/packages/server-shell-setup/README.md @@ -23,6 +23,17 @@ One-command setup for a modern dev environment: `fish`, `nvim`, `nushell`, `bun` **Supported systems**: Arch, Ubuntu/Debian, Android (Termux), macOS, Fedora, Alpine +## Contents + +- [Install](#install) — how to run the installer +- [Components](#components) — what each component installs +- [Fish Aliases](#fish-aliases) — the functions this script adds to fish +- [Command Reference](#command-reference) — common commands for every tool installed +- [Files This Script Touches](#files-this-script-touches) +- [Companion Scripts](#companion-scripts) +- [Troubleshooting](#troubleshooting) +- [Reference Docs](#reference-docs) + ## Install On a fresh server, you may first need to set passwords: @@ -49,34 +60,451 @@ wget -qO- tinyurl.com/shellsetup | bash -s -- all wget -qO- tinyurl.com/shellsetup | bash -s -- starship,docker,node ``` +The `-s --` is what forwards arguments through the pipe to `bash`. Dropping it silently gives you the interactive menu instead. + +### Install Modes + +| Invocation | Behavior | +|------------|----------| +| `\| bash` | Interactive numbered menu, re-prompts until a valid selection is given | +| `\| bash -s -- all` | Everything, unattended | +| `\| bash -s -- fish,node,docker` | Only the named components, unattended | +| `\| bash -s -- sudo` | Passwordless sudo only (CLI-only, not in the menu) | + +Valid CLI component names: `fish`, `nushell`, `nvim`, `helix`, `node`, `bun`, `pacstall`, `docker`, `starship`, `systeminfo`, `code`, `sudo`. An unrecognized name exits with an error and lists the valid ones. + +Two things to know about `all`: +- The interactive menu's "Install Everything" includes `code` (code-server); the CLI `all` argument does not. Pass `code` explicitly if you want it unattended. +- Neither form of `all` includes `sudo` — passwordless sudo is always opt-in. + +Base dependencies (`git`, `wget`, `curl`, `fzf`, `ripgrep`, `python3`, `python3-pip`, `unzip`, `util-linux`) are installed on every run regardless of which components you select, because the fish functions depend on `fzf` and `ripgrep`. + +When the run finishes, the script `exec`s into fish if fish is on the PATH — so your terminal drops straight into the new shell. + ## Components -| Name | Description | -|------|-------------| -| `fish` | Modern shell with auto-suggestions, syntax highlighting, and plugins (oh-my-fish, fzf, z, pisces) | -| `nushell` | Data-oriented shell that handles structured data natively | -| `nvim` | Neovim with [NvChad](https://nvchad.com) config pre-installed | -| `helix` | Modal terminal editor written in Rust, no config needed | -| `node` | Node.js via [Volta](https://volta.sh) version manager (no sudo issues); also installs pnpm, yarn, git0, vite, turbo | -| `bun` | Fast JavaScript runtime, bundler, and package manager | -| `docker` | Docker with rootless mode enabled | -| `starship` | Cross-shell prompt configured for bash, fish, and nushell | -| `systeminfo` | Prints system stats (user, host, disk, RAM, CPU, uptime, IP, location, open ports) on login | -| `pacstall` | AUR-like package manager for Ubuntu/Debian | -| `code` | [code-server](https://github.com/coder/code-server) — VSCode in the browser | -| `sudo` | Enable passwordless sudo for current user | +| Name | Description | Installed via | Verify with | +|------|-------------|---------------|-------------| +| `fish` | Modern shell with auto-suggestions, syntax highlighting, and plugins (oh-my-fish, fzf, z, pisces). Set as your default login shell. | distro package + [oh-my-fish](https://github.com/oh-my-fish/oh-my-fish) | `fish --version` | +| `nushell` | Data-oriented shell that handles structured data natively | `npm i -g nushell` (`pkg` on Termux) | `nu --version` | +| `nvim` | Neovim with [NvChad](https://nvchad.com) config pre-installed | distro package + git clone | `nvim --version` | +| `helix` | Modal terminal editor written in Rust, no config needed | distro package | `hx --version` | +| `node` | Node.js via [Volta](https://volta.sh) version manager (no sudo issues); also installs pnpm, yarn, git0, vite, turbo | [get.volta.sh](https://get.volta.sh) | `node -v`, `volta -v` | +| `bun` | Fast JavaScript runtime, bundler, and package manager | [bun.sh/install](https://bun.sh/install) | `bun --version` | +| `docker` | Docker with rootless mode enabled | get.docker.com + rootless setuptool | `docker version` | +| `starship` | Cross-shell prompt configured for bash, fish, and nushell | [starship.rs/install.sh](https://starship.rs/install.sh) | `starship --version` | +| `systeminfo` | Prints system stats (user, host, disk, RAM, CPU, uptime, IP, location, open ports) on login | `npx about-system@latest` in shell configs | open a new shell | +| `pacstall` | AUR-like package manager for Ubuntu/Debian | [pacstall.dev/q/install](https://pacstall.dev/q/install) | `pacstall -V` | +| `code` | [code-server](https://github.com/coder/code-server) — VSCode in the browser | code-server.dev/install.sh | `code-server --version` | +| `sudo` | Enable passwordless sudo for current user | writes `/etc/sudoers.d/$USER` | `sudo -n true` | + +`pacstall` is Ubuntu/Debian only — on any other distro the script prints an error for that component and continues with the rest. ## Fish Aliases -| Alias | Expands to | -|-------|-----------| -| `in ` | `sudo apt install ` | -| `e ` | `nvim ` | -| `del ` | `sudo rm -rf ` | -| `setup` | Re-run this install script | -| `killport` | Interactive fzf menu to kill a process by port | -| `search ` | Search file names and file contents (via ripgrep) | -| `service_manager` | Interactive fzf menu to start/stop/restart/view systemd services | +These are written as fish functions into `~/.config/fish/functions/` when the `fish` component is installed. Each is a real file you can edit or delete. + +| Alias | Expands to | Notes | +|-------|-----------|-------| +| `in ` | `sudo apt install ` | Hardcoded to apt — edit `in.fish` on non-Debian systems | +| `e ` | `nvim ` | | +| `del ` | `sudo rm -rf ` | No confirmation prompt | +| `setup` | Re-run this install script | Fetches the latest installer and runs the menu | +| `killport` | Interactive fzf menu to kill a process by port | Lists listening TCP ports via `lsof`, then `kill -9`. Falls back to a numbered menu without fzf | +| `search ` | Search file names and file contents (via ripgrep) | Prints filename matches, then content matches with 3 words of context on each side | +| `service_manager` | Interactive fzf menu to start/stop/restart/view systemd services | Lists both system and `--user` units; actions: journal, start, stop, restart, status, edit, enable, disable | + +## Command Reference + +Everything below ships with a default `all` install. This is the day-to-day cheat sheet — the commands you actually reach for on Linux. + +### fish — the shell + +Fish is not POSIX-compatible. Scripts written for bash won't run unmodified; use `bash script.sh` for those. + +| Command | What it does | +|---------|--------------| +| `fish_config` | Open the web-based config UI (themes, prompt, functions) | +| `fish_config theme choose ` | Switch color theme from the terminal | +| `funced ` | Edit a function interactively | +| `funcsave ` | Persist a function to `~/.config/fish/functions/` | +| `functions` | List all defined functions | +| `functions ` | Print a function's source | +| `abbr -a gc git commit` | Add an abbreviation that expands as you type | +| `set -x VAR value` | Export an environment variable for this session | +| `set -U VAR value` | Set a universal variable (persists across sessions) | +| `set -e VAR` | Erase a variable | +| `fish_add_path ~/.local/bin` | Append to `$PATH` permanently and idempotently | +| `history search ` | Search shell history | +| `history delete --contains ` | Remove matching entries from history | +| `bind` | List current key bindings | +| `type -q cmd` | Test whether a command exists (used by the bundled functions) | +| `exec fish` | Reload the shell in place after editing config | + +Key bindings worth knowing: + +| Keys | Action | +|------|--------| +| `→` / `Ctrl+F` | Accept the autosuggestion | +| `Alt+→` | Accept one word of the autosuggestion | +| `↑` / `↓` | History search filtered by what you've typed | +| `Alt+↑` / `Alt+↓` | Search history for the token under the cursor | +| `Ctrl+R` | fzf history search (from the `fzf` omf plugin) | +| `Ctrl+T` | fzf file finder (from the `fzf` omf plugin) | +| `Alt+C` | fzf `cd` into a subdirectory (from the `fzf` omf plugin) | +| `Alt+E` | Edit the current command line in `$EDITOR` | +| `Alt+S` | Prepend `sudo` to the current or previous command | +| `Ctrl+C` / `Ctrl+D` | Cancel line / exit shell | + +Fish plugins this script installs: + +| Plugin | What it adds | +|--------|--------------| +| [oh-my-fish](https://github.com/oh-my-fish/oh-my-fish) (`omf`) | Plugin/theme manager: `omf install `, `omf update`, `omf list`, `omf remove `, `omf theme ` | +| `fzf` | Fuzzy bindings: `Ctrl+T` find file, `Ctrl+R` history, `Alt+C` cd into a subdirectory, `Alt+O` open in `$EDITOR` (legacy bindings stay enabled by default) | +| `z` | Frecency directory jumping: `z proj` cd's to the project dir you use most | +| `pisces` | Auto-closes brackets and quotes as you type | + +### nushell — structured data shell + +Nushell pipes tables, not text. Every command emits structured data you can filter with the same verbs. + +| Command | What it does | +|---------|--------------| +| `nu` | Start nushell | +| `ls \| where size > 1mb` | Filter the directory listing as a table | +| `ls \| sort-by modified \| last 10` | Ten most recently modified files | +| `ps \| where cpu > 10` | Processes above 10% CPU | +| `sys host` | Structured host info (uptime, kernel, hostname) | +| `open file.json` | Parse JSON/YAML/TOML/CSV/XLSX into a table automatically | +| `open data.csv \| get column_name` | Extract one column | +| `open x.json \| to yaml` | Convert between formats | +| `$env.PATH` | Inspect environment as a list | +| `$env.PATH \| split row (char esep)` | PATH as a proper list | +| `help commands` | Browse all builtins | +| `config nu` | Edit the nushell config in `$EDITOR` | +| `^ls` | Escape to the external binary instead of the builtin | + +The script writes `~/.config/nushell/config.nu` with the startup banner disabled and `$env.EDITOR` set to `nvim`. + +### nvim — Neovim with NvChad + +The script clones the [NvChad starter](https://github.com/NvChad/starter) to `~/.config/nvim` and runs a headless `Lazy! sync` to install plugins. An existing config is moved to `~/.config/nvim.bak` first. + +| Keys / command | What it does | +|----------------|--------------| +| `Space` | Leader key | +| `Space + th` | Theme picker (NvChad) | +| `Space + ff` | Find files (Telescope) | +| `Space + fw` | Live grep across the project | +| `Space + fb` | Browse open buffers | +| `Space + fo` | Recently opened files | +| `Ctrl+n` | Toggle the file tree (nvim-tree) | +| `Space + e` | Focus the file tree | +| `Tab` / `Shift+Tab` | Next / previous buffer | +| `Space + x` | Close current buffer | +| `Space + ch` | NvChad cheatsheet — all mappings in one screen | +| `Space + /` | Toggle comment on line or selection | +| `Ctrl+h/j/k/l` | Move between splits | +| `:Lazy` | Plugin manager UI (install, update, profile) | +| `:Mason` | Install LSP servers, formatters, linters | +| `:LspInfo` | Which language servers are attached | +| `:checkhealth` | Diagnose a broken install | +| `:w` / `:q` / `:wq` / `:q!` | Write / quit / write+quit / force quit | + +### helix — modal editor, batteries included + +Helix is selection-first: you select, then act (the reverse of vim). No config or plugins needed for LSP. + +| Keys / command | What it does | +|----------------|--------------| +| `hx ` | Open a file | +| `hx --health` | Check which language servers are detected | +| `Space + f` | Open file picker | +| `Space + /` | Global search across the workspace | +| `Space + b` | Buffer picker | +| `Space + k` | Show hover documentation | +| `Space + r` | Rename symbol (LSP) | +| `Space + a` | Code actions | +| `gd` / `gr` | Go to definition / find references | +| `gg` / `ge` | Top / end of file | +| `x` | Select the current line (repeat to extend) | +| `d` / `c` / `y` / `p` | Delete / change / yank / paste the selection | +| `mi(` / `ma(` | Select inside / around parentheses | +| `Ctrl+w` then `v`/`s` | Vertical / horizontal split | +| `:w` / `:q` / `:wq` | Write / quit / write+quit | +| `:tutor` | Built-in interactive tutorial | +| `:config-open` | Edit `~/.config/helix/config.toml` | + +### node, volta, and the package managers + +Volta installs Node per-user under `~/.volta`, so global installs never need sudo and each project can pin its own toolchain version. + +| Command | What it does | +|---------|--------------| +| `volta install node` | Install the latest Node and make it default | +| `volta install node@20` | Install and default to a specific major | +| `volta install pnpm yarn` | Manage package managers through Volta too | +| `volta pin node@20` | Pin this project's Node version in `package.json` | +| `volta list` | Show installed and pinned tools | +| `volta which node` | Resolve which binary actually runs here | +| `node -v` / `node script.js` | Version / run a script | +| `node --watch script.js` | Re-run on file change | +| `npx ` | Run a package without installing it | +| `npm i -g ` | Install a CLI globally (no sudo, thanks to Volta) | +| `npm ci` | Clean, lockfile-exact install (use in CI) | +| `npm outdated` / `npm audit fix` | Find and patch stale or vulnerable deps | +| `npm run