Handle renaming documents

LICENCE.md

@@ -0,0 +1,32 @@
+# MIT License
+
+Most of this code is copied directly from
+[esbuild](https://github.com/phoenixframework/esbuild) and
+[tailwind](https://github.com/phoenixframework/tailwind), so I guess,
+technically, some or all of these people own the copyrights:
+
+Copyright (c) 2021 Wojtek Mach, José Valim. Copyright (c) 2022 Chris McCord.
+
+And for the bits that I wrote:
+
+Copyright (c) 2024 Catalin Mititiuc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

README.md

@@ -1,21 +1,117 @@
 # Pandoc
 
-**TODO: Add description**
+A watcher and Mix tasks for installing and invoking [pandoc](https://pandoc.org/).
+
+## Requirements
+
+Currently only supports `linux-amd64` architectures.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `pandoc` to your list of dependencies in `mix.exs`:
+If you are going to convert markup in production, then you add `pandoc` as
+dependency on all environments but only start it in dev:
 
 ```elixir
 def deps do
   [
-    {:pandoc, "~> 0.1.0"}
+    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
   ]
 end
 ```
 
-Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
-and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/pandoc>.
+However, if your markup is preconverted during development, then it only needs
+to be a dev dependency:
 
+```elixir
+def deps do
+  [
+    {:pandoc, "~> 0.3", only: :dev}
+  ]
+end
+```
+
+Once installed, change your `config/config.exs` to pick your pandoc version of
+choice:
+
+```elixir
+config :pandoc, version: "3.6.1"
+```
+
+Now you can install pandoc by running:
+
+```bash
+$ mix pandoc.install
+```
+
+And invoke pandoc with:
+
+```bash
+$ mix pandoc default documents/hello.md -o priv/static/posts/hello.html
+```
+
+The executable is kept at `_build/pandoc-TARGET`. Where `TARGET` is your
+system target architecture.
+
+## Profiles
+
+The first argument to `pandoc` is the execution profile. You can define multiple
+execution profiles with the current directory, the OS environment, and default
+arguments to the `pandoc` task:
+
+```elixir
+config :pandoc,
+  version: "3.6.1",
+  default: [
+    args: ~w(--mathjax),
+    cd: Path.expand("../documents", __DIR__)
+  ]
+```
+
+When `mix pandoc default` is invoked, the task arguments will be appended to
+the ones configured above. Note profiles must be configured in your
+`config/config.exs`, as `pandoc` runs without starting your application (and
+therefore it won't pick settings in `config/runtime.exs`).
+
+## Adding to Phoenix
+
+To add `pandoc` to an application using Phoenix, you will need Phoenix v1.6+ and
+the following steps.
+
+First add it as a dependency in your `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:phoenix, "~> 1.6"},
+    {:pandoc, "~> 0.3", runtime: Mix.env() == :dev}
+  ]
+end
+```
+
+Now let's change `config/config.exs` to configure `pandoc` to write to
+`priv/static/posts`:
+
+```elixir
+config :pandoc,
+  version: "3.6.1",
+  default: [
+    args: fn extra_args ->
+      {_, [input_file], _} = OptionParser.parse(extra_args, switches: [])
+      ~w(--output=../priv/static/posts/#{Path.rootname(input_file)}.html)
+    end,
+    cd: Path.expand("../documents", __DIR__)
+  ]
+```
+
+For development, we want to enable the watcher. So find the `watchers`
+configuration in your `config/dev.exs` and add:
+
+```elixir
+pandoc: {Pandoc, :watch, [:default]}
+```
+
+Note we are enabling the file system watcher.
+
+## Licence
+
+pandoc source code is licensed under the MIT License.

config/config.exs

@@ -0,0 +1,7 @@
+import Config
+
+config :pandoc,
+  version: "3.6.1",
+  another: [
+    args: ["--version"]
+  ]

lib/mix/tasks/pandoc.ex

@@ -1,4 +1,32 @@
 defmodule Mix.Tasks.Pandoc do
+  @moduledoc """
+  Invokes pandoc with the given args.
+
+  Usage:
+
+      $ mix pandoc TASK_OPTIONS PROFILE PANDOC_ARGS
+
+  Example:
+
+      $ mix pandoc default documents/hello.md -o priv/static/posts/hello.html
+
+  If pandoc is not installed, it is automatically downloaded. Note the
+  arguments given to this task will be appended to any configured arguments.
+
+  ## Options
+
+    * `--runtime-config` - load the runtime configuration
+      before executing command
+
+  Note flags to control this Mix task must be given before the profile:
+
+      $ mix pandoc --runtime-config default documents/hello.md
+
+  """
+
+  @shortdoc "Invokes pandoc with the profile and args"
+  @compile {:no_warn_undefined, Mix}
+
   use Mix.Task
 
   @impl true
@@ -6,6 +34,11 @@ defmodule Mix.Tasks.Pandoc do
     switches = [runtime_config: :boolean]
     {opts, remaining_args} = OptionParser.parse_head!(args, switches: switches)
 
+    if function_exported?(Mix, :ensure_application!, 1) do
+      Mix.ensure_application!(:inets)
+      Mix.ensure_application!(:ssl)
+    end
+
     if opts[:runtime_config] do
       Mix.Task.run("app.config")
     else
@@ -17,19 +50,11 @@ defmodule Mix.Tasks.Pandoc do
     install_and_run(remaining_args)
   end
 
-  defp install_and_run([profile | args] = _all) do
-    IO.puts("mix task args #{inspect(args)}")
-
-    "documents"
-    |> File.ls!()
-    |> Enum.each(fn path ->
-      all = [profile, path]
-
-      case Pandoc.run(String.to_atom(profile), [path]) do
-        0 -> :ok
-        status -> Mix.raise("`mix pandoc #{Enum.join(all, " ")}` exited with #{status}")
-      end
-    end)
+  defp install_and_run([profile | args] = all) do
+    case Pandoc.install_and_run(String.to_atom(profile), args) do
+      0 -> :ok
+      status -> Mix.raise("`mix pandoc #{Enum.join(all, " ")}` exited with #{status}")
+    end
   end
 
   defp install_and_run([]) do

lib/mix/tasks/pandoc.install.ex

@@ -0,0 +1,70 @@
+defmodule Mix.Tasks.Pandoc.Install do
+  @moduledoc """
+  Installs pandoc under `_build`.
+
+  ```bash
+  $ mix pandoc.install
+  $ mix pandoc.install --if-missing
+  ```
+
+  By default, it installs #{Pandoc.latest_version()} but you can configure it
+  in your config files, such as:
+
+      config :pandoc, :version, "#{Pandoc.latest_version()}"
+
+  ## Options
+
+    * `--runtime-config` - load the runtime configuration before executing
+      command
+
+    * `--if-missing` - install only if the given version does not exist
+  """
+
+  @shortdoc "Installs pandoc under _build"
+  @compile {:no_warn_undefined, Mix}
+
+  use Mix.Task
+
+  @impl true
+  def run(args) do
+    valid_options = [runtime_config: :boolean, if_missing: :boolean]
+
+    {opts, base_url} =
+      case OptionParser.parse_head!(args, strict: valid_options) do
+        {opts, []} ->
+          {opts, Pandoc.default_base_url()}
+
+        {opts, [base_url]} ->
+          {opts, base_url}
+
+        {_, _} ->
+          Mix.raise("""
+          Invalid arguments to pandoc.install, expected one of:
+
+              mix pandoc.install
+              mix pandoc.install 'https://github.com/jgm/pandoc/releases/download/$version/pandoc-$version-$target.tar.gz'
+              mix pandoc.install --runtime-config
+              mix pandoc.install --if-missing
+          """)
+      end
+
+    if opts[:runtime_config], do: Mix.Task.run("app.config")
+
+    if opts[:if_missing] && latest_version?() do
+      :ok
+    else
+      if function_exported?(Mix, :ensure_application!, 1) do
+        Mix.ensure_application!(:inets)
+        Mix.ensure_application!(:ssl)
+      end
+
+      Mix.Task.run("loadpaths")
+      Pandoc.install(base_url)
+    end
+  end
+
+  defp latest_version?() do
+    version = Pandoc.configured_version()
+    match?({:ok, ^version}, Pandoc.bin_version())
+  end
+end

lib/pandoc.ex

@@ -1,13 +1,130 @@
 defmodule Pandoc do
+  # https://github.com/jgm/pandoc/releases
+  @latest_version "3.6.1"
+
   @moduledoc """
-  Documentation for `Pandoc`.
+  Pandoc is an installer, runner and watcher for [pandoc](https://pandoc.org).
+
+  ## Profiles
+
+  You can define multiple pandoc profiles. By default, there is a profile
+  called `:default` which you can configure its args, current directory and
+  environment. You can make the args dynamic by defining a function.
+
+      config :pandoc,
+        version: "#{@latest_version}",
+        default: [
+          args: fn extra_args ->
+            {_, [input_file], _} = OptionParser.parse(extra_args, switches: [])
+            ~w(--output=../priv/static/posts/\#{Path.rootname(input_file)}.html)
+          end,
+          cd: Path.expand("../documents", __DIR__)
+        ]
+
+  ## Pandoc configuration
+
+  There are four global configurations for the pandoc application:
+
+    * `:version` - the expected pandoc version
+
+    * `:version_check` - whether to perform the version check or not.
+      Useful when you manage the pandoc executable with an external
+      tool
+
+    * `:cacerts_path` - the directory to find certificates for
+      https connections
+
+    * `:path` - the path to find the pandoc executable at. By
+      default, it is automatically downloaded and placed inside
+      the `_build` directory of your current app
+
+  Overriding the `:path` is not recommended, as we will automatically download
+  and manage `pandoc` for you. But in case you can't download it, you may want
+  to set the `:path` to a configurable system location.
   """
 
-  def run(profile, ["--watch" | dirs]) do
+  require Logger
+
+  @doc false
+  # Latest known version at the time of publishing.
+  def latest_version, do: @latest_version
+
+  @doc """
+  Returns the configured pandoc version.
+  """
+  def configured_version do
+    Application.get_env(:pandoc, :version, latest_version())
+  end
+
+  @doc """
+  Returns the configuration for the given profile.
+
+  Returns nil if the profile does not exist.
+  """
+  def config_for!(profile) when is_atom(profile) do
+    Application.get_env(:pandoc, profile) ||
+      raise ArgumentError, """
+      unknown pandoc profile. Make sure the profile is defined in your config/config.exs file, such as:
+
+          config :pandoc,
+            version: "#{@latest_version}",
+            #{profile}: [
+              cd: Path.expand("../documents", __DIR__)
+            ]
+      """
+  end
+
+  @doc """
+  Returns the path to the executable.
+
+  The executable may not be available if it was not yet installed.
+  """
+  def bin_path do
+    name = "pandoc-#{target()}"
+
+    Application.get_env(:pandoc, :path) ||
+      if Code.ensure_loaded?(Mix.Project) do
+        relative_build_dir = Mix.Project.build_path() |> Path.dirname() |> Path.relative_to_cwd()
+        project_dir = Path.dirname(Mix.Project.project_file())
+        Path.join([project_dir, relative_build_dir, name])
+      else
+        Path.expand("_build/#{name}")
+      end
+  end
+
+  @doc """
+  Returns the version of the pandoc executable.
+
+  Returns `{:ok, version_string}` on success or `:error` when the executable
+  is not available.
+  """
+  def bin_version do
+    path = bin_path()
+
+    with true <- File.exists?(path),
+         {out, 0} <- System.cmd(path, ["--version"]),
+         [vsn] <- Regex.run(~r/#{Path.basename(path)} ([^\s]+)/, out, capture: :all_but_first) do
+      {:ok, vsn}
+    else
+      _ -> :error
+    end
+  end
+
+  @doc """
+  Starts a file system watcher that runs the given command with `args` when a
+  file event is received for a file that matches the given pattern.
+
+  The given args will be appended to the configured args. The task output will
+  be streamed directly to stdio.
+  """
+  def watch(profile, extra_args \\ [], pattern \\ ~r/\.md$/) when is_atom(profile) do
+    config = config_for!(profile)
+    opts = [dirs: [config[:cd] || File.cwd!()]]
+
     ref =
       __MODULE__.Supervisor
       |> Supervisor.start_child(
-        Supervisor.child_spec({Pandoc.Watcher, [profile, dirs: dirs]},
+        Supervisor.child_spec({Pandoc.Watcher, [profile, opts, pattern, extra_args]},
           restart: :transient,
           id: __MODULE__.Watcher
         )
@@ -23,9 +140,24 @@ defmodule Pandoc do
     end
   end
 
-  def run(profile, extra_args) do
-    config = Application.get_env(:pandoc, profile)
-    args = config[:args] || []
+  @doc """
+  Runs the given command with `args`.
+
+  The given args will be appended to the configured args. The task output will
+  be streamed directly to stdio. It returns the status of the underlying call.
+  """
+  def run(profile, extra_args) when is_atom(profile) and is_list(extra_args) do
+    config = config_for!(profile)
+
+    args =
+      case config[:args] do
+        args_fn when is_function(args_fn) -> args_fn.(extra_args)
+        args -> args || []
+      end
+
+    if args == [] and extra_args == [] do
+      raise "no arguments passed to pandoc"
+    end
 
     opts = [
       cd: config[:cd] || File.cwd!(),
@@ -33,19 +165,215 @@ defmodule Pandoc do
       stderr_to_stdout: true
     ]
 
-    [path] = extra_args
+    {parsed_args, _, _} = OptionParser.parse(args, switches: [output: :string])
+    {_, input_files, _} = OptionParser.parse(extra_args, switches: [])
 
-    args =
-      List.update_at(args, -1, fn v ->
-        Path.join(
-          v,
-          path
-          |> Path.basename()
-          |> String.replace_suffix(".md", ".html")
-          |> String.slice(11..-1//1)
-        )
-      end)
+    if parsed_args[:output] &&
+         not File.cd!(opts[:cd], fn ->
+           input_files |> Enum.map(&File.exists?(&1)) |> Enum.all?()
+         end) do
+      parsed_args[:output] |> Path.expand(opts[:cd]) |> File.rm()
+    else
+      bin_path() |> System.cmd(args ++ extra_args, opts) |> elem(1)
+    end
+  end
 
-    "pandoc" |> System.cmd(args ++ extra_args, opts) |> elem(1)
+  defp start_unique_install_worker() do
+    ref =
+      __MODULE__.Supervisor
+      |> Supervisor.start_child(
+        Supervisor.child_spec({Task, &install/0}, restart: :transient, id: __MODULE__.Installer)
+      )
+      |> case do
+        {:ok, pid} -> pid
+        {:error, {:already_started, pid}} -> pid
+      end
+      |> Process.monitor()
+
+    receive do
+      {:DOWN, ^ref, _, _, _} -> :ok
+    end
+  end
+
+  @doc """
+  Installs, if not available, and then runs `pandoc`.
+
+  This task may be invoked concurrently and it will avoid concurrent installs.
+
+  Returns the same as `run/2`.
+  """
+  def install_and_run(profile, args) do
+    File.exists?(bin_path()) || start_unique_install_worker()
+
+    run(profile, args)
+  end
+
+  @doc """
+  The default URL to install Pandoc from.
+  """
+  def default_base_url do
+    "https://github.com/jgm/pandoc/releases/download/$version/pandoc-$version-$target.tar.gz"
+  end
+
+  @doc """
+  Installs pandoc with `configured_version/0`.
+
+  If invoked concurrently, this task will perform concurrent installs.
+  """
+  def install(base_url \\ default_base_url()) do
+    version = configured_version()
+    tmp_opts = if System.get_env("MIX_XDG"), do: %{os: :linux}, else: %{}
+
+    tmp_dir =
+      freshdir_p(:filename.basedir(:user_cache, "phx-pandoc", tmp_opts)) ||
+        freshdir_p(Path.join(System.tmp_dir!(), "phx-pandoc")) ||
+        raise "could not install pandoc. Set MIX_XGD=1 and then set XDG_CACHE_HOME to the path you want to use as cache"
+
+    url = get_url(base_url)
+    tar = fetch_body!(url)
+
+    case :erl_tar.extract({:binary, tar}, [:compressed, cwd: to_charlist(tmp_dir)]) do
+      :ok -> :ok
+      other -> raise "couldn't unpack archive: #{inspect(other)}"
+    end
+
+    bin_path = bin_path()
+    File.mkdir_p!(Path.dirname(bin_path))
+    [tmp_dir, "pandoc-" <> version, "bin", "pandoc"] |> Path.join() |> File.cp!(bin_path)
+  end
+
+  defp freshdir_p(path) do
+    with {:ok, _} <- File.rm_rf(path),
+         :ok <- File.mkdir_p(path) do
+      path
+    else
+      _ -> nil
+    end
+  end
+
+  defp fetch_body!(url, retry \\ true) do
+    scheme = URI.parse(url).scheme
+    url = String.to_charlist(url)
+    Logger.debug("Downloading pandoc from #{url}")
+
+    {:ok, _} = Application.ensure_all_started(:inets)
+    {:ok, _} = Application.ensure_all_started(:ssl)
+
+    if proxy = proxy_for_scheme(scheme) do
+      %{host: host, port: port} = URI.parse(proxy)
+      Logger.debug("Using #{String.upcase(scheme)}_PROXY: #{proxy}")
+      set_option = if "https" == scheme, do: :https_proxy, else: :proxy
+      :httpc.set_options([{set_option, {{String.to_charlist(host), port}, []}}])
+    end
+
+    # https://erlef.github.io/security-wg/secure_coding_and_deployment_hardening/inets
+    cacertfile = cacertfile() |> String.to_charlist()
+
+    http_options =
+      [
+        ssl: [
+          verify: :verify_peer,
+          cacertfile: cacertfile,
+          depth: 2,
+          customize_hostname_check: [
+            match_fun: :public_key.pkix_verify_hostname_match_fun(:https)
+          ],
+          versions: protocol_versions()
+        ]
+      ]
+      |> maybe_add_proxy_auth(scheme)
+
+    options = [body_format: :binary]
+
+    case {retry, :httpc.request(:get, {url, []}, http_options, options)} do
+      {_, {:ok, {{_, 200, _}, _headers, body}}} ->
+        body
+
+      {true, {:error, {:failed_connect, [{:to_address, _}, {inet, _, reason}]}}}
+      when inet in [:inet, :inet6] and
+             reason in [:ehostunreach, :enetunreach, :eprotonosupport, :nxdomain] ->
+        :httpc.set_options(ipfamily: fallback(inet))
+        fetch_body!(url, false)
+
+      other ->
+        raise """
+        Couldn't fetch #{url}: #{inspect(other)}
+
+        This typically means we cannot reach the source or you are behind a proxy.
+        You can try again later and, if that does not work, you might:
+
+          1. If behind a proxy, ensure your proxy is configured and that
+             your certificates are set via the cacerts_path configuration
+
+          2. Manually download the executable from the URL above and
+             place it inside "_build/pandoc-#{target()}"
+        """
+    end
+  end
+
+  defp fallback(:inet), do: :inet6
+  defp fallback(:inet6), do: :inet
+
+  defp proxy_for_scheme("http") do
+    System.get_env("HTTP_PROXY") || System.get_env("http_proxy")
+  end
+
+  defp proxy_for_scheme("https") do
+    System.get_env("HTTPS_PROXY") || System.get_env("https_proxy")
+  end
+
+  defp maybe_add_proxy_auth(http_options, scheme) do
+    case proxy_auth(scheme) do
+      nil -> http_options
+      auth -> [{:proxy_auth, auth} | http_options]
+    end
+  end
+
+  defp proxy_auth(scheme) do
+    with proxy when is_binary(proxy) <- proxy_for_scheme(scheme),
+         %{userinfo: userinfo} when is_binary(userinfo) <- URI.parse(proxy),
+         [username, password] <- String.split(userinfo, ":") do
+      {String.to_charlist(username), String.to_charlist(password)}
+    else
+      _ -> nil
+    end
+  end
+
+  defp cacertfile() do
+    Application.get_env(:pandoc, :cacerts_path) || CAStore.file_path()
+  end
+
+  defp protocol_versions do
+    if otp_version() < 25, do: [:"tlsv1.2"], else: [:"tlsv1.2", :"tlsv1.3"]
+  end
+
+  defp otp_version do
+    :erlang.system_info(:otp_release) |> List.to_integer()
+  end
+
+  # Available targets: https://github.com/jgm/pandoc/releases
+  # We support only linux-amd64, for now.
+  defp target do
+    case :os.type() do
+      # Assuming it's an x86 CPU
+      {:win32, _} ->
+        raise "pandoc does not currently support OS family: Windows"
+
+      {:unix, osname} ->
+        arch_str = :erlang.system_info(:system_architecture)
+        [arch | _] = arch_str |> List.to_string() |> String.split("-")
+
+        case arch do
+          "amd64" -> "#{osname}-amd64"
+          "x86_64" -> "#{osname}-amd64"
+          _ -> raise "pandoc does not currently support architecture: #{arch_str}"
+        end
+    end
+  end
+
+  defp get_url(base_url) do
+    base_url
+    |> String.replace("$version", configured_version())
+    |> String.replace("$target", target())
   end
 end

lib/pandoc/application.ex

@@ -5,16 +5,37 @@ defmodule Pandoc.Application do
 
   use Application
 
-  @impl true
-  def start(_type, _args) do
-    children = [
-      # Starts a worker by calling: Pandoc.Worker.start_link(arg)
-      # {Pandoc.Worker, arg}
-    ]
+  require Logger
+  import Pandoc, only: [latest_version: 0, configured_version: 0, bin_version: 0]
 
-    # See https://hexdocs.pm/elixir/Supervisor.html
-    # for other strategies and supported options
-    opts = [strategy: :one_for_one, name: Pandoc.Supervisor]
-    Supervisor.start_link(children, opts)
+  @doc false
+  def start(_, _) do
+    if Application.get_env(:pandoc, :version_check, true) do
+      unless Application.get_env(:pandoc, :version) do
+        Logger.warning("""
+        pandoc version is not configured. Please set it in your config files:
+
+            config :pandoc, :version, "#{latest_version()}"
+        """)
+      end
+
+      configured_version = configured_version()
+
+      case bin_version() do
+        {:ok, ^configured_version} ->
+          :ok
+
+        {:ok, version} ->
+          Logger.warning("""
+          Outdated pandoc version. Expected #{configured_version}, got #{version}. \
+          Please run `mix pandoc.install` or update the version in your config files.\
+          """)
+
+        :error ->
+          :ok
+      end
+    end
+
+    Supervisor.start_link([], strategy: :one_for_one, name: Pandoc.Supervisor)
   end
 end

lib/pandoc/watcher.ex

@@ -1,22 +1,27 @@
 defmodule Pandoc.Watcher do
+  @moduledoc false
+
   use GenServer
 
-  @ext ".md"
+  @events MapSet.new([:closed, :deleted, :moved_from, :moved_to])
 
   def start_link(args) do
     GenServer.start_link(__MODULE__, args)
   end
 
-  def init([profile | args]) do
-    {:ok, watcher_pid} = FileSystem.start_link(args)
+  # Callbacks
+
+  @impl true
+  def init([profile, options, pattern, extra_args]) do
+    {:ok, watcher_pid} = FileSystem.start_link(options)
     FileSystem.subscribe(watcher_pid)
-    {:ok, %{watcher_pid: watcher_pid, profile: profile}}
+    {:ok, %{watcher_pid: watcher_pid, profile: profile, pattern: pattern, extra_args: extra_args}}
   end
 
+  @impl true
   def handle_info({:file_event, watcher_pid, {path, events}}, %{watcher_pid: watcher_pid} = state) do
-    case {Path.extname(path), :closed in events} do
-      {@ext, true} -> Pandoc.run(state[:profile], [path])
-      _ -> nil
+    if String.match?(path, state[:pattern]) and update?(events) do
+      Pandoc.install_and_run(state[:profile], [Path.basename(path) | state[:extra_args]])
     end
 
     {:noreply, state}
@@ -25,4 +30,8 @@ defmodule Pandoc.Watcher do
   def handle_info({:file_event, watcher_pid, :stop}, %{watcher_pid: watcher_pid} = state) do
     {:noreply, state}
   end
+
+  defp update?(events) do
+    events |> MapSet.new() |> MapSet.intersection(@events) |> MapSet.size() > 0
+  end
 end

mix.exs

@@ -1,29 +1,46 @@
 defmodule Pandoc.MixProject do
   use Mix.Project
 
+  @version "0.3.2"
+  @source_url "https://webdevcat.me/git/pandoc/"
+
   def project do
     [
       app: :pandoc,
-      version: "0.1.0",
+      version: @version,
       elixir: "~> 1.14",
       deps: deps(),
-      description: "Pandoc",
-      package: []
+      description: "File system watcher and Mix tasks for installing and invoking pandoc",
+      package: [
+        links: %{
+          "pandoc" => "https://pandoc.org/"
+        },
+        licenses: ["MIT"]
+      ],
+      source_url: @source_url,
+      source_url_pattern: "#{@source_url}tree/%{path}#n%{line}",
+      docs: [
+        main: "Pandoc"
+      ],
+      aliases: [test: ["pandoc.install --if-missing", "test"]]
     ]
   end
 
   # Run "mix help compile.app" to learn about applications.
   def application do
     [
-      extra_applications: [:logger],
-      mod: {Pandoc.Application, []}
+      extra_applications: [:logger, inets: :optional, ssl: :optional],
+      mod: {Pandoc.Application, []},
+      env: [default: []]
     ]
   end
 
   # Run "mix help deps" to learn about dependencies.
   defp deps do
     [
-      {:file_system, "~> 1.0"}
+      {:file_system, "~> 1.0"},
+      {:castore, ">= 0.0.0"},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}
     ]
   end
 end

mix.lock

@@ -0,0 +1,10 @@
+%{
+  "castore": {:hex, :castore, "1.0.10", "43bbeeac820f16c89f79721af1b3e092399b3a1ecc8df1a472738fd853574911", [:mix], [], "hexpm", "1b0b7ea14d889d9ea21202c43a4fa015eb913021cb535e8ed91946f4b77a8848"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
+  "ex_doc": {:hex, :ex_doc, "0.35.1", "de804c590d3df2d9d5b8aec77d758b00c814b356119b3d4455e4b8a8687aecaf", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "2121c6402c8d44b05622677b761371a759143b958c6c19f6558ff64d0aed40df"},
+  "file_system": {:hex, :file_system, "1.0.1", "79e8ceaddb0416f8b8cd02a0127bdbababe7bf4a23d2a395b983c1f8b3f73edd", [:mix], [], "hexpm", "4414d1f38863ddf9120720cd976fce5bdde8e91d8283353f0e31850fa89feb9e"},
+  "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
+  "makeup_elixir": {:hex, :makeup_elixir, "1.0.0", "74bb8348c9b3a51d5c589bf5aebb0466a84b33274150e3b6ece1da45584afc82", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "49159b7d7d999e836bedaf09dcf35ca18b312230cf901b725a64f3f42e407983"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
+}

test/pandoc_test.exs

@@ -1,8 +1,111 @@
 defmodule PandocTest do
-  use ExUnit.Case
-  doctest Pandoc
+  use ExUnit.Case, async: true
 
-  test "greets the world" do
-    assert Pandoc.hello() == :world
+  alias Pandoc.Watcher
+  import ExUnit.CaptureIO
+
+  @version Pandoc.latest_version()
+
+  test "run on default" do
+    assert capture_io(fn ->
+             assert Pandoc.run(:default, ["--version"]) == 0
+           end) =~ @version
   end
+
+  test "run on profile" do
+    assert capture_io(fn ->
+             assert Pandoc.run(:another, []) == 0
+           end) =~ @version
+  end
+
+  test "updates on install" do
+    Application.put_env(:pandoc, :version, "3.6")
+
+    Mix.Task.rerun("pandoc.install", ["--if-missing"])
+
+    assert capture_io(fn ->
+             assert Pandoc.run(:default, ["--version"]) == 0
+           end) =~ "3.6"
+
+    Application.delete_env(:pandoc, :version)
+
+    Mix.Task.rerun("pandoc.install", ["--if-missing"])
+
+    assert capture_io(fn ->
+             assert Pandoc.run(:default, ["--version"]) == 0
+           end) =~ @version
+  after
+    Application.delete_env(:pandoc, :version)
+  end
+
+  test "install and run multiple concurrently" do
+    bin_path = Pandoc.bin_path()
+
+    assert :ok = File.exists?(bin_path) && File.rm!(bin_path)
+
+    results =
+      [:extra1, :extra2, :extra3]
+      |> Enum.map(fn profile ->
+        Application.put_env(:pandoc, profile, args: ["--version"])
+
+        Task.async(fn ->
+          capture_io(fn ->
+            ret_code = Pandoc.install_and_run(profile, [])
+            # Let the first finished task set the binary file to read and execute only,
+            # so that the others will fail if they try to overwrite it.
+            File.chmod!(bin_path, 0o500)
+            ret_code == 0
+          end)
+        end)
+      end)
+      |> Task.await_many(:infinity)
+
+    File.chmod!(bin_path, 0o700)
+    assert Enum.all?(results)
+  end
+
+  test "installs with custom URL" do
+    assert :ok =
+             Mix.Task.rerun("pandoc.install", [
+               "https://github.com/jgm/pandoc/releases/download/$version/pandoc-$version-$target.tar.gz"
+             ])
+  end
+
+  test "starts watching and writes to stdio" do
+    in_tmp("documents", fn ->
+      task = Task.async(fn -> Pandoc.watch(:default) end)
+      %{pid: pid, ref: ref} = task
+      :timer.sleep(200)
+
+      {_, watcher_pid, _, _} =
+        Pandoc.Supervisor
+        |> Supervisor.which_children()
+        |> Enum.find(fn
+          {Watcher, _, _, _} -> true
+          _ -> false
+        end)
+
+      assert capture_io(fn ->
+               # Redirect watcher output to current process so it can be captured
+               Process.group_leader(watcher_pid, Process.group_leader())
+               File.write!("hello.md", "# hello")
+               Task.yield(task, 200)
+             end) =~ ~s{<h1 id="hello">hello</h1>\n}
+
+      assert :ok = Supervisor.terminate_child(Pandoc.Supervisor, Watcher)
+      assert_receive {:DOWN, ^ref, :process, ^pid, :normal}, 1000
+    end)
+  after
+    File.rm_rf!(tmp_path())
+  end
+
+  defp in_tmp(which, function) do
+    path = tmp_path(which)
+    File.rm_rf!(path)
+    File.mkdir_p!(path)
+    File.cd!(path, function)
+  end
+
+  defp tmp_path, do: Path.expand("../tmp", __DIR__)
+  defp tmp_path(extension), do: Path.join(tmp_path(), extension)
 end