feat(attach): add OrgAttach:attach_url()

This corresponds to the Emacs function `org-attach-url`. It also adds
some functionality from the Emacs core that we don't get for free.

Author: broken-pen

docs/configuration.org

@@ -566,6 +566,36 @@ See [[https://orgmode.org/manual/Property-Inheritance.html][Property Inheritance
 - Default: ~{ [':tangle'] = 'no', [':noweb']  = no }~
 Default header args for extracting source code. See [[#extract-source-code-tangle][Extract source code (tangle)]] for more details.
 
+*** org_resource_download_policy
+:PROPERTIES:
+:CUSTOM_ID: org_resource_download_policy
+:END:
+- Type: ='always' | 'prompt' | 'safe' | 'never'=
+- Default: ='prompt'=
+Policy applied to requests to obtain remote resources.
+
+- =always= - Always download remote resources (dangerous!)
+- =prompt= - Prompt before downloading an unsafe resource
+- =safe= - Only download resources allowed by [[#org_safe_remote_resources][org_safe_remote_resources]]
+- =never= - Never download any resources
+
+In Emacs Orgmode, this affects keywords like =#+setupfile= and =#+include=
+on export, =org-persist-write:url=; and =org-attach-url= in non-interactive
+sessions. Nvim Orgmode currently does not use this option, but defines it
+for future use.
+
+*** org_safe_remote_resources
+:PROPERTIES:
+:CUSTOM_ID: org_safe_remote_resources
+:END:
+- Type: =string[]=
+- Default: ={}=
+
+List of regex patterns matching safe URIs. URI regexps are applied to both
+URLs and Org files requesting remote resources. The test uses
+=vim.regex()=, so the regexes are always interpreted as magic and
+case-sensitive.
+
 *** calendar_week_start_day
 :PROPERTIES:
 :CUSTOM_ID: calendar_week_start_day

lua/orgmode/attach/core.lua

@@ -307,11 +307,36 @@ function AttachCore:attach(node, file, opts)
   end)
 end
 
----@class orgmode.attach.core.attach_buffer.opts
+---@class orgmode.attach.core.attach_url.opts
 ---@inlinedoc
 ---@field set_dir_method fun(): OrgPromise<orgmode.attach.core.new_method>
 ---@field new_dir fun(): OrgPromise<string | nil>
 
+---Download a file from a URL and attach it to the current outline node.
+---
+---@param node OrgAttachNode
+---@param url string URL to the file to attach
+---@param opts orgmode.attach.core.attach_url.opts
+---@return OrgPromise<string|nil> attachment_name
+function AttachCore:attach_url(node, url, opts)
+  local basename = basename_safe(url)
+  return self:get_dir_or_create(node, opts.set_dir_method, opts.new_dir):next(function(attach_dir)
+    local attach_file = vim.fs.joinpath(attach_dir, basename)
+    return fileops.download_file(url, attach_file, { exist_ok = false }):next(function(success)
+      if not success then
+        return nil
+      end
+      EventManager.dispatch(EventManager.event.AttachChanged:new(node, attach_dir))
+      node:add_auto_tag()
+      local link = self.links:store_link_to_attachment({ attach_dir = attach_dir, original = url })
+      vim.fn.setreg(vim.v.register, link)
+      return basename
+    end)
+  end)
+end
+
+---@alias orgmode.attach.core.attach_buffer.opts orgmode.attach.core.attach_url.opts
+
 ---Attach buffer's contents to current outline node.
 ---
 ---Throws a file-exists error if it would overwrite an existing filename.

lua/orgmode/attach/fileops.lua

@@ -339,4 +339,52 @@ function M.remove_directory(path, opts)
   end)
 end
 
+--[[
+-- File downloads, based on <https://github.com/neovim/neovim/pull/33964>
+-- In a future Neovim version, this might land as `vim.net.download()`.
+--]]
+
+---Download a file via `curl`.
+---Curl is invoked via `vim.system` and downloads the file at the given `url`
+---to the file at the path `dest.
+---A non-zero exit code or any output to standard error is treated as an error.
+---Curl follows redirects with no limit.
+---If `exist_ok` is true, the returned promise is immediately rejected if
+---`dest` already exists.
+---The options `retry` and `verbose` are passed through directly to curl as
+---the corresponding command-line arguments.
+---@param url string
+---@param dest string
+---@param opts? {clobber: boolean?, retry: integer?, verbose: boolean?}
+---@return OrgPromise<true> success
+function M.download_file(url, dest, opts)
+  opts = opts or {}
+  if not opts.exist_ok and M.exists(dest) then
+    return Promise.reject('EEXIST: ' .. dest)
+  end
+  local args = { 'curl' }
+  if opts.verbose then
+    table.insert(args, '--verbose')
+  else
+    vim.list_extend(args, { '--silent', '--show-error', '--fail' })
+  end
+  vim.list_extend(args, {
+    '--retry',
+    tostring(opts.retry or 3),
+    '--location',
+    '--output',
+    dest,
+    url,
+  })
+  return Promise.new(function(resolve, reject)
+    vim.system(args, { text = true }, function(res)
+      if res.code ~= 0 or res.stderr ~= '' then
+        reject(res.stderr ~= '' and res.stderr or 'Download failed')
+      else
+        resolve(true)
+      end
+    end)
+  end)
+end
+
 return M

lua/orgmode/attach/init.lua

@@ -4,6 +4,7 @@ local Input = require('orgmode.ui.input')
 local Menu = require('orgmode.ui.menu')
 local Promise = require('orgmode.utils.promise')
 local config = require('orgmode.config')
+local remote_resource = require('orgmode.objects.remote_resource')
 local ui = require('orgmode.attach.ui')
 local utils = require('orgmode.utils')
 
@@ -65,6 +66,13 @@ function Attach:_build_menu()
       return self:attach_lns()
     end,
   })
+  menu:add_option({
+    label = 'Attach a file by download from URL.',
+    key = 'u',
+    action = function()
+      return self:attach_url()
+    end,
+  })
   menu:add_option({
     label = "Attach a buffer's contents.",
     key = 'b',
@@ -356,18 +364,62 @@ function Attach:attach(file, opts)
     :wait(MAX_TIMEOUT)
 end
 
----@class orgmode.attach.attach_buffer.Options
+---@class orgmode.attach.attach_url.Options
 ---@inlinedoc
 ---@field visit_dir? boolean if true, visit the directory subsequently using
 ---                          `org_attach_visit_command`
 ---@field node? OrgAttachNode
 
+---Download a URL.
+---
+---@param url? string
+---@param opts? orgmode.attach.attach_url.Options
+---@return string|nil attachment_name
+function Attach:attach_url(url, opts)
+  local node = opts and opts.node or self.core:get_current_node()
+  local visit_dir = opts and opts.visit_dir or false
+  return Promise
+    .resolve()
+    :next(function()
+      if not url then
+        return Input.open('URL of the file to attach: ')
+      end
+      return remote_resource.should_fetch(url):next(function(ok)
+        if not ok then
+          error(("remote resource %s is unsafe, won't download"):format(url))
+        end
+        return url
+      end)
+    end)
+    ---@param chosen_url? string
+    :next(function(chosen_url)
+      if not chosen_url then
+        return nil
+      end
+      return self.core:attach_url(node, chosen_url, {
+        set_dir_method = get_set_dir_method(),
+        new_dir = ui.ask_attach_dir_property,
+      })
+    end)
+    :next(function(attachment_name)
+      if attachment_name then
+        utils.echo_info(('File %s is now an attachment'):format(attachment_name))
+        if visit_dir then
+          local attach_dir = self.core:get_dir(node)
+          self.core:reveal_nvim(attach_dir)
+        end
+      end
+      return attachment_name
+    end)
+    :wait(MAX_TIMEOUT)
+end
+
 ---Attach buffer's contents to current outline node.
 ---
 ---Throws a file-exists error if it would overwrite an existing filename.
 ---
 ---@param buffer? string | integer A buffer number or name.
----@param opts? orgmode.attach.attach_buffer.Options
+---@param opts? orgmode.attach.attach_url.Options
 ---@return string|nil attachment_name
 function Attach:attach_buffer(buffer, opts)
   local node = opts and opts.node or self.core:get_current_node()

lua/orgmode/config/_meta.lua

@@ -252,6 +252,8 @@
 ---@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 org_resource_download_policy 'always' | 'prompt' | 'safe' | 'never' Policy for downloading files from the Internet. Default: 'prompt'
+---@field org_safe_remote_resources string[] List of regex patterns for URIs considered always safe to download from. Default: {}
 ---@field win_split_mode? 'horizontal' | 'vertical' | 'auto' | 'float' | string[] How to open agenda and capture windows. Default: 'horizontal'
 ---@field win_border? 'none' | 'single' | 'double' | 'rounded' | 'solid' | 'shadow' | string[] Border configuration for `win_split_mode = 'float'`. Default: 'single'
 ---@field notifications? OrgNotificationsConfig Notification settings

lua/orgmode/config/defaults.lua

@@ -87,6 +87,8 @@ local DefaultConfig = {
     'fallback_folder_format',
   },
   org_attach_sync_delete_empty_dir = 'ask',
+  org_resource_download_policy = 'prompt',
+  org_safe_remote_resources = {},
   win_split_mode = 'horizontal',
   win_border = 'single',
   notifications = {