eblume/hephaestus
1
0
Fork 0
generated from eblume/project-template
Code Issues Pull requests Projects Releases 10 Packages Wiki Activity Actions

heph.nvim: plug-and-play managed daemon (autostart, self-heal, client/server guardrail)

Browse source 
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>
This commit is contained in:
Erich Blume 2026-06-02 09:32:32 -07:00
commit e3db2ac550
11 changed files with 277 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/reference/heph-nvim.md
View file

@ -24,7 +24,7 @@ buffers; the daemon owns all storage and sync. Built in checkpointed slices on
| `node` | Buffer-backed nodes. A node is a buffer named `heph://node/<id>` with `buftype=acwrite`; `BufReadCmd` loads the body via `node.get`, `BufWriteCmd` saves the whole buffer via `node.update`. |
| `link` | Parse the `[[wiki-link]]` under the cursor (mirroring `extract.rs` grammar) and follow it via `node.resolve` (exact, never fuzzy `search`). Unresolved links are allowed. |
| `journal` | Open/create a dated journal node (idempotent — deterministic id). |
| `daemon` | Locate / spawn / readiness-poll `hephd` (shared with the e2e harness). |
| `daemon` | Managed-daemon lifecycle: `ensure` (connect if a daemon already serves the socket, else spawn one we own), `stop_spawned` (kill only what we spawned, on exit), readiness-poll. Shared with the e2e harness. |
| `config` / `init` | `setup(opts)`, socket resolution, default keymaps. |
| `command` | The `:Heph <subcommand>` dispatch + completion. |
@ -32,6 +32,18 @@ Surfaces never touch SQLite — every operation is a daemon RPC (tech-spec §3).
The plugin is **mode-agnostic**: Tactical/Strategic/Organizational are
plugin-side compositions of daemon primitives, not daemon concepts.
## Daemon lifecycle
`setup({})` is **plug-and-play** by default (`autostart = true`): if nothing is
serving the socket, the plugin spawns a local `hephd` against the default XDG
paths, kills only the daemon *it* spawned on `VimLeavePre`, and **self-heals** —
`rpc.call` retries once through a respawn hook if the connection drops. It only
ever spawns when nothing is already serving the socket, so a `server`/`client`
daemon you started is respected. With `autostart = false` the plugin **connects
only** and warns/errors if unreachable — for when you run your own daemon. The
`$HEPH_SOCKET` / `$HEPH_DB` env knobs (and `mise run dev`) isolate a dev Neovim
onto a separate daemon + DB so real data is never touched.
## Daemon RPC dependencies
Beyond the existing methods (tech-spec §6), the plugin relies on