feat(attach): add OrgAttach:sync()

This corresponds to the Emacs function `org-attach-sync`.

Author: broken-pen

docs/configuration.org

@@ -1250,6 +1250,19 @@ Be careful when changing this setting. If you remove a function, previously
 created attachment folders may be no longer mapped correctly and Org may be
 unable to detect them.
 
+*** org_attach_sync_delete_empty_dir
+:PROPERTIES:
+:CUSTOM_ID: org_attach_sync_delete_empty_dir
+:END:
+- Type: ='always'|'ask'|'never'=
+- Default: ='ask'=
+
+Determines whether to delete empty directories during [[https://orgmode.org/manual/Attachment-defaults-and-dispatcher.html*index-C_002dc-C_002da-z][org_attach_sync]].
+
+- =never= - never delete empty directories
+- =ask= - ask the user whether to delete
+- =always= - delete empty directories without asking
+
 ** Mappings
 :PROPERTIES:
 :CUSTOM_ID: mappings

lua/orgmode/attach/core.lua

@@ -497,4 +497,49 @@ function AttachCore:delete_all(node, recursive)
   end)
 end
 
+---Return true if the directory contains any files without trailing `~` in
+---their name. Trailing `~` is Emacs convention for swap files.
+---
+---@param directory string
+---@return boolean
+local function has_any_non_litter_files(directory)
+  ---@param name string
+  return fileops.iterdir(directory):any(function(name)
+    return not vim.endswith(name, '~')
+  end)
+end
+
+---Synchronize the current outline node with its attachments.
+---
+---Useful after files have been added/removed externally. The Option
+---`org_attach_sync_delete_empty_dir` controls the behavior for empty
+---attachment directories. (This ignores files whose name ends with
+---a tilde `~`.)
+---
+---@param node OrgAttachNode
+---@param delete_empty_dir fun(): OrgPromise<boolean>
+---@return OrgPromise<string|nil> attach_dir_if_deleted
+function AttachCore:sync(node, delete_empty_dir)
+  local attach_dir = self:get_dir_or_nil(node)
+  if not attach_dir then
+    self:untag(node)
+    return Promise.resolve()
+  end
+  local non_empty = has_any_non_litter_files(attach_dir)
+  if non_empty then
+    node:add_auto_tag()
+    return Promise.resolve()
+  else
+    node:remove_auto_tag()
+  end
+  return delete_empty_dir():next(function(do_delete)
+    if not do_delete then
+      return Promise.resolve()
+    end
+    return fileops.remove_directory(attach_dir, { recursive = true }):next(function()
+      return attach_dir
+    end)
+  end)
+end
+
 return AttachCore

lua/orgmode/attach/init.lua

@@ -136,6 +136,13 @@ function Attach:prompt()
       return self:unset_directory()
     end,
   })
+  menu:add_option({
+    label = 'Synchronize this task with its attachment directory.',
+    key = 'z',
+    action = function()
+      return self:sync()
+    end,
+  })
   menu:add_option({ label = 'Quit', key = 'q' })
   menu:add_separator({ icon = ' ', length = 1 })
 
@@ -589,4 +596,30 @@ function Attach:delete_all(force, node)
     :wait(MAX_TIMEOUT)
 end
 
+---Synchronize the current outline node with its attachments.
+---
+---Useful after files have been added/removed externally. The Option
+---`org_attach_sync_delete_empty_dir` controls the behavior for empty
+---attachment directories. (This ignores files whose name ends with
+---a tilde `~`.)
+---
+---@param node? OrgAttachNode
+---@return nil
+function Attach:sync(node)
+  node = node or self.core:get_current_node()
+  local function delete_empty_dir()
+    local opt = config.org_attach_sync_delete_empty_dir
+    if opt == 'always' then
+      return Promise.resolve(true)
+    elseif opt == 'never' then
+      return Promise.resolve(false)
+    elseif opt == 'ask' then
+      return ui.yes_or_no_or_cancel_slow('Attachment directory is empty. Delete? ')
+    else
+      return Promise.reject(('invalid value for org_attach_sync_delete_empty_dir: %s'):format(opt))
+    end
+  end
+  return self.core:sync(node, delete_empty_dir):wait(MAX_TIMEOUT)
+end
+
 return Attach