generated from eblume/project-template
Erich Blume
652d2e89e6
Some checks failed
Build / validate (pull_request) Failing after 10m32s
- mise-tasks/dev runs the working-tree hephd on isolated .dev/ paths (gitignored) so in-repo development never touches the installed daemon's data; point a dev nvim at it via HEPH_SOCKET/HEPH_DB. - docs/how-to/install-heph.md: install heph/hephd from the forge (build from source), the lazy.nvim `dir` setup for the subdir plugin, and dev isolation. - gitignore .dev/ and the transient .claude scheduled-task state. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
---
|
|
title: Install heph (and isolate dev)
|
|
modified: 2026-06-02
|
|
tags:
|
|
- how-to
|
|
---
|
|
|
|
# Install heph (and isolate dev)
|
|
|
|
How to install `heph`/`hephd` from the forge and run the `heph.nvim` plugin,
|
|
**isolated** from in-repo development so the two never share data. No prebuilt
|
|
binaries yet — everything builds from source (works on macOS/arm64,
|
|
linux/arm64, linux/amd64).
|
|
|
|
## 1. Install the binaries from the forge
|
|
|
|
Build and install `heph` + `hephd` to `~/.cargo/bin` (on `PATH`) from a forge
|
|
ref. Until v1 is tagged, install from the branch:
|
|
|
|
```bash
|
|
cargo install --locked \
|
|
--git ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
|
|
--branch feature/v1-prototype \
|
|
heph hephd
|
|
```
|
|
|
|
Re-run with `--tag vX.Y.Z` once a release is cut. This needs forge SSH access
|
|
(an unlocked 1Password / ssh-agent key).
|
|
|
|
The **installed** daemon owns the default paths — socket
|
|
`$XDG_RUNTIME_DIR/heph/hephd.sock`, DB `$XDG_DATA_HOME/heph/heph.db` — i.e. your
|
|
real data.
|
|
|
|
## 2. The Neovim plugin
|
|
|
|
`heph.nvim` lives in a subdirectory of the monorepo, and lazy.nvim can't load a
|
|
subdir plugin from a bare git URL (it puts the clone *root* on `runtimepath`).
|
|
For now, point lazy at a dedicated checkout via `dir`:
|
|
|
|
```bash
|
|
git clone --branch feature/v1-prototype \
|
|
ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.git \
|
|
~/.local/share/heph/checkout
|
|
```
|
|
|
|
```lua
|
|
-- lazy.nvim spec
|
|
{
|
|
dir = vim.fn.expand("~/.local/share/heph/checkout/heph.nvim"),
|
|
config = function()
|
|
require("heph").setup({}) -- plug-and-play: spawns + manages its own hephd
|
|
end,
|
|
}
|
|
```
|
|
|
|
`setup({})` is plug-and-play — it starts and supervises a local `hephd` against
|
|
the default paths, so you don't need a separate service. Update the plugin by
|
|
`git pull`ing the checkout. (A future split of `heph.nvim` into its own forge
|
|
repo will make this a normal `{ "eblume/heph.nvim" }` spec.)
|
|
|
|
## 3. Isolate development
|
|
|
|
In-repo development must not touch the installed store. Run the dev daemon on
|
|
separate paths and point a dev Neovim at it:
|
|
|
|
```bash
|
|
mise run dev # runs the working-tree hephd on .dev/hephd.sock + .dev/heph.db
|
|
```
|
|
|
|
```bash
|
|
# dev Neovim — the plugin reads these envs and targets the dev daemon
|
|
HEPH_SOCKET="$PWD/.dev/hephd.sock" HEPH_DB="$PWD/.dev/heph.db" nvim
|
|
```
|
|
|
|
The installed plugin (no envs) talks to the installed daemon; the dev Neovim
|
|
talks to the dev daemon. They never share a socket or DB. `.dev/` is gitignored.
|
|
|
|
## Related
|
|
|
|
- [[heph-nvim]] — the plugin surface and its managed-daemon lifecycle
|
|
- [[tech-spec]] — §3.1 runtime modes; the daemon's exclusive DB lock
|