generated from eblume/project-template
Erich Blume
e3db2ac550
The plugin now manages its own hephd by default (autostart = true): if nothing is serving the socket it spawns a local daemon against the default XDG paths, kills only what it spawned on VimLeavePre, and self-heals — rpc.call retries once through a respawn hook when the connection drops (the prior owner releases the DB lock on exit, so a respawn can claim it). - daemon.ensure() connects to an already-running daemon (any mode) or spawns one we own; stop_spawned()/is_managed() track lifecycle. - A server/client daemon you started is always respected (spawn only when nothing serves the socket). autostart = false → connect-only, warns/errors if down, and clears the self-heal hook so it fails loudly. - config: autostart defaults true; new `db` option; $HEPH_SOCKET / $HEPH_DB fallbacks isolate a dev Neovim onto a separate daemon + DB. e2e: managed_daemon_spec covers autostart spawn, self-heal-after-kill, and connect-only error. 10 specs green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
75 lines
3.2 KiB
Markdown
75 lines
3.2 KiB
Markdown
# heph.nvim
|
|
|
|
The primary surface for [hephaestus](../README.md) — an obsidian.nvim
|
|
replacement that is a thin client of the local `hephd` daemon over its
|
|
unix-socket JSON-RPC (tech-spec §8). Notes, journals, and tasks are edited as
|
|
ordinary Neovim buffers; saving routes through the daemon.
|
|
|
|
> **Status:** built in checkpointed slices. **11a (this slice)** delivers the
|
|
> RPC client, buffer-backed editing, `[[wiki-link]]` following, and the daily
|
|
> journal. Task/agenda views (`:Heph next`/`list`/capture), the per-task log,
|
|
> and promotion arrive in 11b/11c. See tech-spec §14.
|
|
|
|
## How it works
|
|
|
|
- **Buffer-backed nodes.** A node is edited in a buffer named
|
|
`heph://node/<id>`. Opening it loads the markdown body via `node.get`; `:w`
|
|
saves the whole buffer back via `node.update` (the backend diffs it into a
|
|
text CRDT, so sending the full buffer is correct). `buftype=acwrite`.
|
|
- **Links.** Press `<CR>` on a `[[wiki-link]]` to jump to its node (resolved
|
|
exactly via `node.resolve`). Unresolved links are allowed — they just notify.
|
|
- **Journal.** `:Heph today` (or `:Heph journal YYYY-MM-DD`) opens a dated
|
|
journal note; the id is deterministic so reopening is idempotent.
|
|
|
|
## Setup
|
|
|
|
Requires Neovim ≥ 0.10 and `hephd` on `PATH` (e.g. `cargo install`ed). By
|
|
default the plugin is **plug-and-play** — it starts and manages its own `hephd`:
|
|
|
|
```lua
|
|
require("heph").setup({}) -- spawns a local hephd against the default XDG paths
|
|
```
|
|
|
|
- **`autostart = true`** (default): if nothing is serving the socket, the plugin
|
|
spawns a local `hephd`, kills only what *it* spawned on exit, and **self-heals**
|
|
(respawns + reconnects if the daemon dies mid-session).
|
|
- **Running your own daemon** (a `server`/`client` architecture, or a launchd
|
|
service)? Set `autostart = false` and point at its socket — the plugin then
|
|
**connects only**, never spawning over your daemon, and warns if it's
|
|
unreachable. A daemon already serving the socket is always respected, even with
|
|
`autostart = true` (the plugin only spawns when nothing is there).
|
|
|
|
```lua
|
|
require("heph").setup({
|
|
-- socket = "...", -- default: $HEPH_SOCKET, else hephd's XDG path
|
|
-- db = "...", -- DB for an autostarted daemon ($HEPH_DB, else default)
|
|
-- autostart = true, -- false = connect-only (you run hephd yourself)
|
|
-- bin = "hephd", -- daemon binary for autostart
|
|
-- keymaps = true, -- <leader>h* maps
|
|
})
|
|
```
|
|
|
|
**Dev isolation:** set `$HEPH_SOCKET` / `$HEPH_DB` (or run `mise run dev`) so a
|
|
development Neovim drives a separate daemon + DB and never touches real data.
|
|
|
|
## Commands
|
|
|
|
| Command | Action |
|
|
|---|---|
|
|
| `:Heph today` | Open today's journal |
|
|
| `:Heph journal <YYYY-MM-DD>` | Open a dated journal |
|
|
| `:Heph follow` | Follow the `[[link]]` under the cursor (also `<CR>`) |
|
|
| `:Heph open <id>` | Open a node buffer by id |
|
|
|
|
## Tests
|
|
|
|
The e2e suite drives the plugin in headless Neovim against a real daemon:
|
|
|
|
```bash
|
|
mise run test-nvim # builds hephd, runs the headless e2e suite
|
|
```
|
|
|
|
The suite uses a small self-contained busted-style runner
|
|
(`tests/e2e/runner.lua`) — no external plugins and no network, so it is
|
|
deterministic. Dev runs use system-installed Neovim (≥ 0.10) + rustc; CI runs
|
|
the same suite inside a Dagger container that provides them (slice 11c).
|