hephaestus/heph.nvim/lua/heph/task.lua

--- Task actions (tech-spec §8): capture, attention, state, skip, log. Actions
--- that operate on "the current task" resolve it from the buffer — either the
--- buffer is a `task` node, or it is a task's canonical-context doc, in which
--- case we follow the `canonical-context` backlink to its owning task.

local rpc = require("heph.rpc")
local util = require("heph.util")

local M = {}

--- Capture a committed task. `opts`: attention, do_date, late_on, recurrence,
--- project. Returns the created task.
function M.capture(title, opts)
  opts = opts or {}
  return rpc.call("task.create", {
    title = title,
    attention = opts.attention,
    do_date = opts.do_date,
    late_on = opts.late_on,
    recurrence = opts.recurrence,
    project_id = opts.project,
  })
end

--- The committed task id associated with the current buffer, or nil.
function M.current_task_id()
  local buf = vim.api.nvim_get_current_buf()
  local id = vim.b[buf].heph_node_id
  if not id then
    return nil
  end
  if vim.b[buf].heph_node_kind == "task" then
    return id
  end
  -- A canonical-context doc: its owning task is the src of the
  -- canonical-context link pointing here.
  for _, l in ipairs(rpc.call("links.backlinks", { id = id })) do
    if l.link_type == "canonical-context" then
      return l.src_id
    end
  end
  return nil
end

local function with_task(action, what)
  local id = M.current_task_id()
  if not id then
    util.notify("no task associated with this buffer", vim.log.levels.WARN)
    return nil
  end
  action(id)
  if what then
    util.notify(what)
  end
  return id
end

--- Mark the current task done/dropped (recurring tasks roll forward on done).
function M.set_state_current(state)
  return with_task(function(id)
    rpc.call("task.set_state", { id = id, state = state })
  end, "task " .. state)
end

--- Set the current task's attention.
function M.set_attention_current(attention)
  return with_task(function(id)
    rpc.call("task.set_attention", { id = id, attention = attention })
  end, "attention → " .. attention)
end

--- Skip the current recurring task's occurrence (advance without logging).
function M.skip_current()
  return with_task(function(id)
    rpc.call("task.skip", { id = id })
  end, "occurrence skipped")
end

--- Append a line to the current task's log (the resumption breadcrumb).
function M.log_append_current(text)
  if not text or #text == 0 then
    util.notify("nothing to log", vim.log.levels.WARN)
    return nil
  end
  return with_task(function(id)
    rpc.call("log.append", { task_id = id, text = text })
  end, "logged")
end

return M