id       = "newsbeuter"
name     = "Newsbeuter"
homepage = "https://github.com/akrennmair/newsbeuter"
description = "Newsbeuter is an RSS feed reader for the text console."
executables   = ["newsbeuter", "podbeuter"]
# "It is designed to run on Unix-like operating systems such as GNU/Linux and
# FreeBSD" (README). No Windows build.
platforms = ["macos", "linux"]

[dotfiles]
# Newsbeuter was abandoned in 2017 — its README's first line points at newsboat
# as "an actively maintained fork" — but the files below are still on the
# machines of everyone who ran it, which is what this entry records.

# doc/chapter-firststeps.txt: "you can either add URLs to the configuration
# file $HOME/.newsbeuter/urls or you can import an OPML file", and "Several
# aspects of newsbeuter's behaviour can be configured via a configuration file,
# by default $HOME/.newsbeuter/config."
#
# The manual's "XDG Base Directory Support" section gives the second location
# and how the two split:
#
#   "If these directories exist or the environment variables $XDG_CONFIG_HOME
#    and $XDG_DATA_HOME are set, newsbeuter will use these directories,
#    otherwise it will default to '~/.newsbeuter' as its configuration
#    directory."
#   'config', 'urls'  ->  '$HOME/.config/newsbeuter/'
#   'cache.db', 'history.search', 'history.cmdline', 'queue'
#                     ->  '$HOME/.local/share/newsbeuter/'
#
# so the two configuration files are [configHome] and the four state files are
# [xdgData]. A machine has one layout or the other; a consumer skips the half
# that is absent.
paths = [
  "[configHome]/newsbeuter/config",
  "[configHome]/newsbeuter/urls",
  "~/.newsbeuter/config",
  "~/.newsbeuter/urls",
]

# The four files the same section moves to the data directory: cache.db is the
# downloaded articles, the two history files are what was typed at the search
# and command prompts, and queue is podbeuter's download list. None is under a
# path above, so there is nothing to carve out of what is; both layouts are
# named so a consumer syncing whole directories skips them either way.
exclude = [
  "[xdgData]/newsbeuter/",
  "~/.newsbeuter/cache.db",
  "~/.newsbeuter/history.search",
  "~/.newsbeuter/history.cmdline",
  "~/.newsbeuter/queue",
]

# The config file is not a credential end to end — it is key bindings, colours,
# format strings and the browser and player commands. Only the service
# passwords are lifted out below. Note for a consumer that the `urls` file can
# also carry credentials, because a feed URL may embed them; the manual's own
# advice is to "make sure $HOME/.newsbeuter/urls has the appropriate
# permissions". Those are inside URLs the user wrote, with no key to name, so
# they are left to the consumer's content scan.
secret = []

# Both spellings of the config file, because newsbeuter reads whichever layout
# the machine uses and the two share a last segment, so the sibling check
# requires them together.
#
# Newsbeuter grew a remote-service mode, and each service has its own login and
# password configuration commands, listed in the manual's chapters for them:
# oldreader-password, newsblur-password, feedhq-password, ttrss-password and
# ocnews-password, each documented alongside a `<service>-login`. Each also has
# `-passwordfile` and `-passwordeval` variants that name a file or a command
# instead of the secret itself; those start with the same text and are matched
# too, which over-classifies a file name — the safe direction.
[[dotfiles.secret_paths]]
file  = ["[configHome]/newsbeuter/config", "~/.newsbeuter/config"]
match = { prefix = [
  "oldreader-password",
  "newsblur-password",
  "feedhq-password",
  "ttrss-password",
  "ocnews-password",
] }

[commands]
format = 1
label = "Start newsbeuter"
description = "Start the feed reader with optional alternate URL, cache and config files, or import and export OPML. Logging and read-article sync options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = false, short_attached = false, short_bundles = false }

[[commands.source]]
id = "help"
kind = "manual"
url = "https://manpages.debian.org/unstable/newsbeuter/newsbeuter.1.en.html"
revision = "debian unstable"
evidence = """
-e              export OPML feed to stdout
-r              refresh feeds on start
-i <file>       import OPML file
-u <urlfile>    read RSS feed URLs from <urlfile>
-c <cachefile>  use <cachefile> as cache file
-C <configfile> read configuration from <configfile>
-X              clean up cache thoroughly
-q              quiet startup
"""

[[commands.field]]
id = "refresh"
label = "Refresh feeds on start"
type = "boolean"
option = ["-r"]
sources = ["help"]

[[commands.field]]
id = "urlfile"
label = "URL file"
type = "path"
option = ["-u"]
path = { kind = "file", role = "input" }
sources = ["help"]

[[commands.field]]
id = "cachefile"
label = "Cache file"
type = "path"
option = ["-c"]
path = { kind = "file", role = "output", must_exist = false }
sources = ["help"]

[[commands.field]]
id = "configfile"
label = "Config file"
type = "path"
option = ["-C"]
path = { kind = "file", role = "input" }
sources = ["help"]

[[commands.field]]
id = "import_opml"
label = "Import OPML file"
type = "path"
option = ["-i"]
path = { kind = "file", role = "input" }
sources = ["help"]

[[commands.field]]
id = "export_opml"
label = "Export OPML to stdout"
type = "boolean"
option = ["-e"]
sources = ["help"]

[[commands.field]]
id = "cleanup"
label = "Clean up cache thoroughly"
type = "boolean"
option = ["-X"]
sources = ["help"]

[[commands.field]]
id = "quiet"
label = "Quiet startup"
type = "boolean"
option = ["-q"]
sources = ["help"]

[[commands.task]]
id = "start"
label = "Start and refresh"
fields = ["refresh"]
set = { refresh = [true] }

[[commands.task]]
id = "import"
label = "Import OPML"
fields = ["import_opml"]
required = ["import_opml"]

[[commands.task]]
id = "export"
label = "Export OPML"
fields = ["export_opml"]
set = { export_opml = [true] }

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["refresh", "urlfile", "import_opml", "export_opml"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["cachefile", "configfile", "cleanup", "quiet"]