What a `plushook` plugin needs

An up-front explanation of why it exists

Specific important points to convey:

This should never need to be used by the end user: all tasks a user would need to do should be handled by porcelain plugins
This should never never be used by a developer in their plugin's code. Plugins are supposed to actually call plushook directly by path, and any calls to the plushu porcelain are an antipattern. Besides, calling this will just introduce a bunch of weird fragmentary points (like a way for a plugin to make -i mean something other than "take stdin" - also, since using this implies -i (see below), there's overhead that calling it directly will avoid).
This is to make it slightly easier to fix things without having to run commands / log in as root on the remote server. It makes situations where things have gotten intractably munged, and your only hope is to shove your hands into Plushu's guts and massage its heart, slightly less icky.
Installing this is still a massive footgun, and mostly just gives you a ton of ways to break your server by directly calling trusted commands that would normally have had their input determined in the middle of some code and sanitized/sanity-checked by porcelain.
If you ever run into a case where you have to use this, when one of those aforementioned processes has failed in an unexpected way, that is the only time you should ever use this. Once you've fixed it for yourself, you should file an issue / submit a pull request to whatever plugin or plugins triggered the problem, to ensure it will never happen for you or anybody else ever again.
If you really find yourself needing to use this repeatedly to do something remotely non-broken, you've found something that calls for new porcelain. Submit an issue suggesting / pull request providing it, or just make a whole new dang plugin/command (remember any plugin can call any other plugin's plushooks). See some of the plugins and features of plugins used on sandbox.plushu.org.
A way to set environment variables

This should probably be a separate opts plugin(s). You can do -e, --env, and something=value as three different types of plugin. This isn't a responsibility for this plugin, but it is a feature one may need alongside this, as some plushooks employ environment variables for certain mechanics (like the ones that use semaphores to avoid infinite loops, like those of the app/repo two-way binding plugin).

Also good to keep this in separate plugins since letting users specify arbitrary environment variables is even more of a security hole than letting them do arbitrary plushooks (not just in terms of Shellshock - it's why SSH doesn't forward / accept environment variables without lots of explicit configuration).

Other "porcelain plumbing" plugins

Sometimes plugins have features that haven't had any porcelain-based way of accessing them, sort of like how Atari Flashback systems have a pin-out for a cartridge slot on the mainboard but no actual console slot on the device. (RC scripts, like plushurc and (probably more so) the receive and build RCs in apps, are a good example of this right now: without any porcelain commands to edit them, the files have to get there, essentially, by magic.)

Usually / ideally, the place for this is to actually create a new porcelain plugin to do what you want with these dangling features (see the last bullet of the first section). For instance, if you wanted a way to add/remove PLUSHU_TRACE=1 from .plushurc, you could make a plugin for that (and, indeed, that's an issue on the feature wishlist for the plushu-trace plugin right now).

Also, the more open-ended aspects of these dangling are traditionally made for The Admin, which is a thoroughly different role (if not a different person) from The User. There's no mainstream way of accessing them for The User because The User shouldn't be messing with features that are that essential.

However, when THERE'S JUST NO TIME to get it right, you want to hack it RIGHT NOW NOW, and you can't (or don't want to) get out of your comfort zone as The User, you can use a plugin like this.

Other potential plugins of this level of debugging/hacking:

edit-plushu-file (opens $EDITOR for a named file in $PLUSHU_ROOT)
(mv|cp|rm|ln|touch|sed)-plushu-file (same basic thing for all these basic operations)
set-plushu-file (Echoes argument into a file as content)

Really though, at that point you might as well just use some Plushu plugin that exposes performing arbitrary commands / interactive sessions, at which point you're kind of subverting a lot of the whole point of Plushu (a streamlined porcelain experience via commands) in the first place. Again - that is what The Admin role is supposed to be for. (Add sudoers rules to let users sudo as the plushu user if you want non-root users to be able to do Plushu admin stuff with non-Plushu shells.)

The pithy slogan to sum it up: porcelain plumbing is an antipattern. Surfacing a high-level UX allowing you to perform low-level implementation tasks is a sign that your abstraction is leaking too heavily.

(And yes, this incidentally asserts the conclusion that Git has a ton of leaky abstractions. It does.)

Always specifying -i

Since this plugin's use should be sparing, the overhead for this in all cases where this plugin is needed is acceptable, especially considering that it obviates the need to add a long-/short-opts source (which would also needlessly pollute plushu's opts space). (If a plushook hinges on not inheriting stdin, you'll have to pipe in /dev/null manually to get the same effect as not specifying -i.)

plushu / plushu-plushook-plugin