feat(attach): add event to delete attachments of archived headlines

This corresponds to the Emacs function
`org-attach-archive-delete-maybe`.

Author: broken-pen

docs/configuration.org

@@ -1242,6 +1242,16 @@ If not =false=, store a link with [[#org_store_link][org_store_link]] when attac
 - =file= - store a =[[file:attach_dir/name]]= link
 - =original= - store a =[[file:original/location]]= link
 
+*** org_attach_archive_delete
+:PROPERTIES:
+:CUSTOM_ID: org_attach_archive_delete
+:END:
+- Type: ='always' | 'ask' | 'never'=
+- Default: ='never'=
+
+Determines whether attachments are deleted automatically whenever a subtree
+is moved to an archive file. The value ='ask'= means to ask the user.
+
 *** org_attach_id_to_path_function_list
 :PROPERTIES:
 :CUSTOM_ID: org_attach_id_to_path_function_list

lua/orgmode/attach/init.lua

@@ -597,6 +597,23 @@ function Attach:delete_all(force, node)
     :wait(MAX_TIMEOUT)
 end
 
+---Maybe delete subtree attachments when archiving.
+---
+---This function is called via the `OrgHeadlineArchivedEvent`. The option
+---`org_attach_archive_delete' controls its behavior."
+---
+---@param headline OrgHeadline
+---@return nil
+function Attach:maybe_delete_archived(headline)
+  local delete = config.org_attach_archive_delete
+  if delete == 'always' then
+    self:delete_all(true, AttachNode.from_headline(headline))
+  end
+  if delete == 'ask' then
+    self:delete_all(false, AttachNode.from_headline(headline))
+  end
+end
+
 ---Synchronize the current outline node with its attachments.
 ---
 ---Useful after files have been added/removed externally. The Option

lua/orgmode/capture/init.lua

@@ -3,6 +3,7 @@ local fs = require('orgmode.utils.fs')
 local config = require('orgmode.config')
 local Templates = require('orgmode.capture.templates')
 local Template = require('orgmode.capture.template')
+local EventManager = require('orgmode.events')
 local Menu = require('orgmode.ui.menu')
 local Range = require('orgmode.files.elements.range')
 local CaptureWindow = require('orgmode.capture.window')
@@ -300,6 +301,7 @@ function Capture:refile_file_headline_to_archive(headline)
   local headline_category = headline:get_category()
   local outline_path = headline:get_outline_path()
 
+  EventManager.dispatch(EventManager.event.HeadlineArchived:new(headline, destination_file))
   return self
     :_refile_from_org_file({
       source_headline = headline,

lua/orgmode/config/_meta.lua

@@ -248,6 +248,7 @@
 ---@field org_attach_visit_command string | fun(dir: string) Command or Lua function used to open a directory. Default: 'edit'
 ---@field org_attach_use_inheritance 'always' | 'selective' | 'never' Determines whether headlines inherit the attachments directory of their parents. Default: 'selective'
 ---@field org_attach_store_link_p 'original' | 'file' | 'attached' | false If true, attaching a file stores a link to it. Default: 'attached'
+---@field org_attach_archive_delete 'always' | 'ask' | 'never' Determines whether to delete a headline's attachments when it is archived. Default: 'never'
 ---@field org_attach_id_to_path_function_list (string | fun(id: string): (string|nil))[] List of functions used to derive the attachments directory from an ID property.
 ---@field org_attach_sync_delete_empty_dir 'always' | 'ask' | 'never' Determines whether to delete empty directories when using `org.attach.sync()`. Default: 'ask'
 ---@field win_split_mode? 'horizontal' | 'vertical' | 'auto' | 'float' | string[] How to open agenda and capture windows. Default: 'horizontal'

lua/orgmode/config/defaults.lua

@@ -80,6 +80,7 @@ local DefaultConfig = {
   org_attach_visit_command = 'edit',
   org_attach_use_inheritance = 'selective',
   org_attach_store_link_p = 'attached',
+  org_attach_archive_delete = 'never',
   org_attach_id_to_path_function_list = {
     'uuid_folder_format',
     'ts_folder_format',

lua/orgmode/events/listeners/attach_maybe_delete_archived.lua

@@ -0,0 +1,4 @@
+---@param event OrgHeadlineArchivedEvent
+return function(event)
+  require('orgmode').attach:maybe_delete_archived(event.headline)
+end

lua/orgmode/events/listeners/init.lua

@@ -1,6 +1,7 @@
 local Events = require('orgmode.events.types')
 local AlignTags = require('orgmode.events.listeners.align_tags')
 local ClockOut = require('orgmode.events.listeners.clock_out')
+local AttachMaybeDeleteArchived = require('orgmode.events.listeners.attach_maybe_delete_archived')
 
 return {
   [Events.TodoChanged] = {
@@ -13,4 +14,7 @@ return {
   [Events.HeadlinePromoted] = {
     AlignTags,
   },
+  [Events.HeadlineArchived] = {
+    AttachMaybeDeleteArchived,
+  },
 }

lua/orgmode/events/types/headline_archived_event.lua

@@ -0,0 +1,20 @@
+---@class OrgHeadlineArchivedEvent: OrgEvent
+---@field type string
+---@field headline OrgHeadline
+---@field destination_file OrgFile
+local HeadlineArchivedEvent = {
+  type = 'orgmode.headline_archived',
+}
+
+---@param headline OrgHeadline
+---@param destination_file OrgFile
+---@return OrgHeadlineArchivedEvent
+function HeadlineArchivedEvent:new(headline, destination_file)
+  local obj = setmetatable({}, self)
+  self.__index = self
+  obj.headline = headline
+  obj.destination_file = destination_file
+  return obj
+end
+
+return HeadlineArchivedEvent

lua/orgmode/events/types/init.lua

@@ -8,4 +8,5 @@ return {
   HeadingToggled = require('orgmode.events.types.heading_toggled'),
   AttachChanged = require('orgmode.events.types.attach_changed_event'),
   AttachOpened = require('orgmode.events.types.attach_opened_event'),
+  HeadlineArchived = require('orgmode.events.types.headline_archived_event'),
 }