History

Erich Blume 0e9cfc1fd7 Some checks failed Build / validate (pull_request) Failing after 5m1s Details feat(nvim): frontmatter edit surface — diff block into RPCs on save (§8.3) Node buffers now open with the editable YAML frontmatter block on top (node.get {frontmatter: true}); on :w, `frontmatter.lua` parses the block, diffs it against what was rendered, and routes each changed field to the right RPC: - title → node.update rename - attention → task.set_attention - do_date/late_on/recurrence → task.set_schedule (YYYY-MM-DD → local-ms; a removed line clears via null) - project → task.set_project (resolved by name) - tags → tag.add / tag.remove A mistyped state surfaces the daemon's validation error; a buffer with no block edits no metadata (deleting the block can't wipe tags). Body rides node.update as before (the store strips any echoed frontmatter). Body-position features are content-relative, so the prepended block doesn't disturb them; e2e specs that targeted absolute line 1 now locate body lines by content via a new `h.find` helper. New frontmatter_spec covers render + the full diff→RPC round-trip. 21 nvim e2e specs green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>		2026-06-03 11:44:39 -07:00
..
lua/heph	feat(nvim): frontmatter edit surface — diff block into RPCs on save (§8.3)	2026-06-03 11:44:39 -07:00
plugin	heph.nvim: plug-and-play managed daemon (autostart, self-heal, client/server guardrail)	2026-06-02 09:37:49 -07:00
tests/e2e	feat(nvim): frontmatter edit surface — diff block into RPCs on save (§8.3)	2026-06-03 11:44:39 -07:00
README.md	heph.nvim: plug-and-play managed daemon (autostart, self-heal, client/server guardrail)	2026-06-02 09:37:49 -07:00

README.md

heph.nvim

The primary surface for hephaestus — 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 installed). By default the plugin is plug-and-play — it starts and manages its own hephd:

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).

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:

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).