pagefindex

# Additional Pagefindex Features

## Config changes: Rename `:command` option to `:run_with`

This is a prerequisite for other changes.

## `run_with`: Improve `:global` command resolution

`:global` should only pass if `pagefind_extended` or `pagefind` can be found in
`$PATH`. This is important for other features below.

## New `:version` config and its impact on `run_with`

We should be able to specify a specific version to be run. We should support
_simple_ Elixir version specifiers (e.g., `~> 1.4`, `>= 1.3.1`, but _not_
`>= 1.3.1 and < 2.0.0`) for comparison and allow `:latest` or `"latest"` (the
default value).

We need a global compile-time value, `@latest_version "1.4.0"` that can be used
for comparison.

Using the version for runtime is relatively easy for `bunx`, `pnpx`, and `npx`:
append `@{version}` to the run command: `bunx pagefind@{version}` (e.g.,
`bunx pagefind@1.3.0`, `bunx pagefind@latest`). Where it gets hard is converting
`~> version` to an appropriate NPM versioning scheme because the NPM versioning
tags are stupid beyond belief.

Using the version for `:global` is harder. We have to run `pagefind --version`
(which outputs `pagefind {version}`). If the version doesn't match and is _below
the specifier range_, we should fail to run with an appropriate error message.
If the version is `latest`, then compare against `@latest_version`.

We do no version validation for `{:command, args}` tuples.

## `:local` install

The other `pagefind` package is modelled on the `tailwind` and `esbuild`
packages, which will install the configured version. They, however, don't have
the `bunx` etc. option that we have.

Add `:local` option to `run_with` configuration, which resolves _after_
`:global` in `:auto` mode.

We will download the appropriate _extended_ version of pagefind from
<https://github.com/CloudCannon/pagefind/releases/download/v{version}/pagefind-v{version}-{target}.tar.gz>.

We need to support the following architectures:

- `aarch64-apple-darwin`
- `aarch64-unknown-linux-musl`
- `x86_64-apple-darwin`
- `x86_64-pc-windows-msvc`
- `x86_64-unknown-linux-musl`

This will be determined from `:os.type()`,
`:erlang_system_info(:system_archiecture)` (the first value when split on `-`),
and `:erlang.system_info(:wordsize) * 8`. The download should be performed
either with `:inets` and `:ssl` (see `esbuild` package for details) or by using
`req`.

The tar needs to be extracted with `:erl_tar` and it should contain one binary
which we should write to a common location based on the resolved version. These
packages use something like this:

```elixir
  def bin_path do
    name = "esbuild-#{target()}"


    Application.get_env(:esbuild, :path) ||
      if Code.ensure_loaded?(Mix.Project) do
        Path.join(Path.dirname(Mix.Project.build_path()), name)
      else
        Path.expand("_build/#{name}")
      end
  end
```

It must be set to permission 0o755. On macOS, the executable must be removed
prior to being written.

## Configuration Sources

By _default_, `Pagefindex.Tableau` will find its configuration (including
`enabled`) in `config :tableau, Pagefindex.Tableau, …`. The core application
will accept passed configuration but if no configuration is provided, it should
check `config :pagefindex, config` For all configuration values _other_ than
`enabled`, the hierarchy is:

    defaults < config :pagefindex, config < config, :tableau, Pagefindex.Tableau, …

## Extended configuration

There is extended configuration available. I haven't decided whether I want to
support that configuration directly _or_ if we want to encourage the use of
`pagefind.toml`, `pagefind.yml`, `pagefind.yaml`, or `pagefind.json` file as
documented <https://pagefind.app/docs/config-sources/>. There is no option to
specify a configuration file (it only looks in the current directory), so I'm
not sure.

We already specify `--site`/`-s` and replace that. I _think_ that the rest are
well served by the `args` configuration option, but that's not available for
`mix`.

We should support all options -- except `-s`/`--site` (which we already support)
as pass-through options to `pagefind`.

```
Options:
  -s, --site <SITE>
          The location of your built static website
      --output-subdir <OUTPUT_SUBDIR>
          Where to output the search bundle, relative to the processed site
      --output-path <OUTPUT_PATH>
          Where to output the search bundle, relative to the working directory of the command
      --root-selector <ROOT_SELECTOR>
          The element Pagefind should treat as the root of the document. Usually you will want to use the data-pagefind-body attribute instead.
      --exclude-selectors <EXCLUDE_SELECTORS>
          Custom selectors that Pagefind should ignore when indexing. Usually you will want to use the data-pagefind-ignore attribute instead.
      --glob <GLOB>
          The file glob Pagefind uses to find HTML files. Defaults to "**/*.{html}"
      --force-language <FORCE_LANGUAGE>
          Ignore any detected languages and index the whole site as a single language. Expects an ISO 639-1 code.
      --include-characters <INCLUDE_CHARACTERS>
          Include these characters when indexing and searching words. Useful for sites documenting technical topics such as programming languages.
      --serve
          Serve the source directory after creating the search index
  -v, --verbose
          Print verbose logging while indexing the site. Does not impact the web-facing search.
  -q, --quiet
          Only log errors and warnings while indexing the site. Does not impact the web-facing search.
      --silent
          Only log errors while indexing the site. Does not impact the web-facing search.
  -l, --logfile <LOGFILE>
          Path to a logfile to write to. Will replace the file on each run
  -k, --keep-index-url
          Keep "index.html" at the end of search result paths. Defaults to false, stripping "index.html".
      --write-playground
          Output the Pagefind Playground to <bundle_dir>/playground/ when building the search index. By default, this is only available via --serve.
  -h, --help
          Print help
  -V, --version
          Print version
```