meejah / fowl

Forward over Wormhole: streams over magic-wormhole Dilation connections
MIT License
29 stars 3 forks source link

re-architect CLI #15

Closed meejah closed 9 months ago

meejah commented 10 months ago

Inspired by discussion from https://github.com/meejah/fowl/pull/11 I think it makes sense to split the command-line into two:

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!)

meejah commented 9 months ago

Done, mostly, in https://github.com/meejah/fowl/pull/23