fowld: plumbing command that accepts commands on stdin and produces messages on stdout (i.e. a stdin/out line-based protocol with JSON messages).
fowl: porcelain for users (everything accomplished by running fowld under the hood)
This means that "integrations" (like https://sr.ht/~meejah/pear-on/) would typically run fowld directly and issue it commands. End-users would typically run fowl ...
So, options similar to ssh's -L and -R can live on the fowl process. The target for these options (and their output) is humans -- friendly text can be produced, and whatever makes sense for humans is what makes sense for options.
On the other hand, the fowld protocol should be well-specified, stable and versioned -- integrations can be confident that a new version won't break their interaction (due to a new or removed option etc). (Note: the protocol is NOT yet in any way stable).
Philosophy-wise, fowld should take very minimal (ideally zero) command-line argument and do all interaction via its well-specified line-based JSON protocol. All output and input MUST be machine parse-able and stable. The fowl command (and sub-commands) produces human-centric input and while it "should" be stable between versions, nobody should depend on parsing it.
I've used the "porcelain" and "plumbing" words the same way Git does. This is an analogy to the fact that the guts of water / waste systems is the "plumbing" like pipes etc (which most humans never see or interact with) while the "porcelain" is the sink or toilet which humans are expected to interact with (so it better be nice!)
Inspired by discussion from https://github.com/meejah/fowl/pull/11 I think it makes sense to split the command-line into two:
fowld
: plumbing command that accepts commands on stdin and produces messages on stdout (i.e. a stdin/out line-based protocol with JSON messages).fowl
: porcelain for users (everything accomplished by runningfowld
under the hood)This means that "integrations" (like https://sr.ht/~meejah/pear-on/) would typically run
fowld
directly and issue it commands. End-users would typically runfowl ...
So, options similar to ssh's
-L
and-R
can live on thefowl
process. The target for these options (and their output) is humans -- friendly text can be produced, and whatever makes sense for humans is what makes sense for options.On the other hand, the
fowld
protocol should be well-specified, stable and versioned -- integrations can be confident that a new version won't break their interaction (due to a new or removed option etc). (Note: the protocol is NOT yet in any way stable).Philosophy-wise,
fowld
should take very minimal (ideally zero) command-line argument and do all interaction via its well-specified line-based JSON protocol. All output and input MUST be machine parse-able and stable. Thefowl
command (and sub-commands) produces human-centric input and while it "should" be stable between versions, nobody should depend on parsing it.I've used the "porcelain" and "plumbing" words the same way Git does. This is an analogy to the fact that the guts of water / waste systems is the "plumbing" like pipes etc (which most humans never see or interact with) while the "porcelain" is the sink or toilet which humans are expected to interact with (so it better be nice!)