Introduce support for user-provided extensions

This change introduces support for discovering and executing
user-provided extensions to the program. Extensions are useful for
allowing users to provide additional functionality on top of the
nitrocli proper. Implementation wise we stick to an approach similar to
git or cargo subcommands in nature: we search the directories listed in
the PATH environment variable for a file that starts with "nitrocli-",
followed by the extension name. This file is then executed. It is
assumed that the extension recognizes (or at least not prohibits) the
following arguments: --nitrocli (providing the path to the nitrocli
binary), --model (with the model passed to the main program), and
--verbosity (the verbosity level).

2 files changed, 53 insertions, 0 deletions

diff --git a/doc/nitrocli.1 b/doc/nitrocli.1
index 61764dd..832c90d 100644
--- a/doc/nitrocli.1
+++ b/doc/nitrocli.1
@@ -318,6 +318,18 @@ The admin PIN cannot be unblocked.
 This operation is equivalent to the unblock PIN option provided by \fBgpg\fR(1)
 (using the \fB\-\-change\-pin\fR option).
 
+.SS Extensions
+In addition to the above built-in commands, \fBnitrocli\fR supports
+user-provided functionality in the form of extensions. An extension can be any
+executable file whose filename starts with "nitrocli-" and that is discoverable
+through lookup via the \fBPATH\fR environment variable. Those executables can be
+invoked as regular subcommands (without the need of the prefix; e.g., an
+extension with the name "nitrocli-otp-cache" could be invoked as "nitrocli
+otp-cache").
+.P
+More information on how to write extensions can be found in the Extensions
+section below.
+
 .SH CONFIG FILE
 \fBnitrocli\fR tries to read the configuration file at
 \fB${XDG_CONFIG_HOME}/nitrocli/config.toml\fR (or
@@ -406,6 +418,47 @@ for the \fBuser\fR type.
 .B NITROCLI_PASSWORD
 A password used by commands that require one (e.g., \fBhidden open\fR).
 
+.SH EXTENSIONS
+\fBnitrocli\fR supports user-provided extensions that are executable files whose
+filename starts with "nitrocli-" and that are discoverable through lookup via
+the \fBPATH\fR environment variable.
+
+The program conveys basic configuration information to any extension being
+started this way. Specifically, it will set each environment variable as
+described in the Configuration subsection of the Environment section above, if
+the corresponding \fBnitrocli\fR program configuration was set. In addition, the
+following variable will be set unconditionally:
+.TP
+.B NITROCLI_BINARY
+The absolute path to the \fBnitrocli\fR binary through which the extension was
+invoked. This path may be used to recursively invoke \fBnitrocli\fR to implement
+certain functionality.
+
+.P
+All other variables present in the environment will be passed through to the
+extension verbatim.
+.P
+Newer versions of the program reserve the right to set additional environment
+variables inside the "NITROCLI_" namespace. As such, extensions are advised to
+not define custom variables with this prefix. However, "NITROCLI_EXT_" is
+provided specifically for this purpose. To further avoid conflicts between
+extensions, it is recommended that this prefix be followed by the extension's
+name (uppercased).
+
+.P
+Extensions may optionally read or write persistent data of various forms.
+Similar to the main program, extensions should follow the XDG Base Directory
+Specification as a guideline where to store such data. More specifically, the
+following conventions should be followed:
+
+For configuration data, \fB${XDG_CONFIG_HOME}/\fIextension/\fR is the preferred
+directory, where \fIextension\fR is the full extension name, including the
+"nitrocli-" prefix. The recommended configuration format is TOML. If only a
+single configuration file is used, \fBconfig.toml\fR is the recommended name.
+
+Similarly, regular data should reside in \fB${XDG_DATA_HOME}/\fIextension/\fR
+and cached data be stored in \fB${XDG_CACHE_HOME}/\fIextension/\fR.
+
 .SH FILES
 .TP
 .B ${XDG_CONFIG_HOME}/nitrocli/config.toml
diff --git a/doc/nitrocli.1.pdf b/doc/nitrocli.1.pdf
index 2c63658..47dadda 100644
--- a/doc/nitrocli.1.pdf
+++ b/doc/nitrocli.1.pdf