hephaestus/heph.nvim/lua/heph/init.lua

--- heph.nvim — the primary surface for hephaestus (tech-spec §8): an
--- obsidian.nvim replacement that is a thin client of the local `hephd` over
--- its unix-socket JSON-RPC. This module is the public entry point.

local config = require("heph.config")

local M = {}

--- The resolved config from the last `setup` (nil before setup).
M.config = nil

--- Configure the plugin. `opts.socket` overrides the daemon socket path;
--- `opts.keymaps = false` disables the default keymaps. Idempotent.
---
--- The plugin is **connect-only** — it never spawns or supervises a `hephd`.
--- Run the daemon as an OS service with `heph daemon start` ([[run-the-daemon]]);
--- this just connects to it. If nothing is serving the socket, we notify once
--- with guidance and let later calls retry (a plain reconnect, never a spawn).
function M.setup(opts)
  local cfg = vim.tbl_deep_extend("force", config.defaults, opts or {})
  cfg.socket = config.resolve_socket(cfg.socket)
  M.config = cfg

  local rpc = require("heph.rpc")
  rpc.setup(cfg.socket)

  -- A cheap liveness probe so a missing daemon is reported up front, not as a
  -- cryptic error on the first command.
  local ok = pcall(function()
    rpc.call("health", {})
  end)
  if not ok then
    require("heph.util").notify(
      "no hephd at " .. cfg.socket .. " — run `heph daemon start`",
      vim.log.levels.WARN
    )
  end

  config.apply_keymaps(cfg)
  return M
end

return M