$ cats nobody@supertxt.net:specs/command-reflection.s.txt

# Command Reflection

Commands are the best entity to understand the nature of their inputs and outputs since they define their usage patterns. Other entities in a system can use a command's help to customize the user experience, such as navigation of links in the output, or the file extension of the expected output from a command's arguments. The general mechanism behind this reflectionis the presence of a special "--srefl" argument that either puts the command into a reflective mode, or fails if the operation is unsupported/impossible.

## Invocation

.txt
<command> --srefl=<operation> [options...] [arguments...]

The command is any available command on the path or fully qualified. The "--srefl" option is to request that the command enter a reflective mode with the operation.The options and arguments may be valid/invalid for the command. Some potential operations are enumerated in the following sections of this specification.

If anything goes wrong then the command will exit with a non-zero exit code to signal a failure.

## Redirect operation

.txt
--srefl=redirect

The caller invokes the command with the "--srefl" option along with the rest of the options/arguments that produced some output. The contents of a link that comes from that output is sent through STDIN. Upon successful completion the command returns a command-line that will fetch the destination of that link. If for any reason this is not possible then the command exits with a non-zero exit code.

## File extension operation

.txt
--srefl=extension

The caller invokes the command with the "--srefl" option along with the rest of the options/arguments to produce some output. Upon successful completion the command returns a single line of output (without a newline) with the file extension of the content expected on STDOUT if that command is invoked without the reflection. If for any reason this is not possible then the command exits with a non-zero exit code.

If file extension reflection operation fails then a tool might assume that the command output is ".txt" but with safeguards in place because of very large and/or binary outputs.

HAVE SOME FEEDBACK ON THIS DOCUMENT?

You can provide a conventional comment on this document.

.sh
ssh nobody@supertxt.net ccmnt specs/command-reflection.s.txt <<EOF
suggestion: Here's my actionable suggestion.
EOF