File Coverage

=head1 NAME

App::FileSync::CLI - the filesync, filesync-admin and filesync-server commands

=head1 SYNOPSIS

        # bin/filesync
        use App::FileSync::CLI;
        exit App::FileSync::CLI::run_client(@ARGV);

=head1 DESCRIPTION

Each C<run_*> function runs one command line and returns the exit code; it
never dies.  Errors are reported through the logger (or standard error if the
settings that configure the logger are themselves broken), without Perl file
and line numbers.  Text output goes to standard output; C<--json> prints one
JSON document instead.

Client exit codes: 0 ok, 1 fatal, 2 another run holds the lock, 3 completed
with warnings, 4 verification found drift.  Admin: 0, 1 and 4.

=head1 FUNCTIONS

=head2 run_client

Documented with L</run_server> below.

=head2 run_admin

Documented with L</run_server> below.

=head2 run_server

Purpose: run C<filesync>, C<filesync-admin> or C<filesync-server>.

Args: the command line, without the program name.

Returns: the exit code.

Side Effects: whatever the command does; prints to standard output and logs
to standard error.  C<run_server> speaks the protocol on standard input and
output and refuses to run on a terminal unless C<FILESYNC_ALLOW_TTY> is set.

Usage:

        exit App::FileSync::CLI::run_client(@ARGV);

=head3 EXAMPLE

        my $code = App::FileSync::CLI::run_client('sync', '--repo', 'docs', '--json');
        my $code = App::FileSync::CLI::run_admin('--root', '/srv/filesync', 'repo', 'list');

=head3 API SPECIFICATION

=head4 INPUT

        [ { name => 'args', type => 'arrayref' } ]        # passed as a list

=head4 OUTPUT

        { type => 'integer', min => 0, max => 255 }

=head3 MESSAGES

        Key                 Meaning                                   Resolution
        cli.unknown_command the command is not known                  run "filesync help"
        cli.usage.*         the options could not be parsed           see the usage line
        cli.unexpected      extra arguments were given                remove them
        cli.required        a required argument is missing            supply it
        cli.no_repos        no repos are configured                   filesync init
        cli.no_repo         the named repo is not configured          check --repo
        cli.need_repo       several repos and no --repo               pass --repo
        cli.init.*          init was given an unusable value          see the message
        cli.server.*        the server was started wrongly            fix authorized_keys

=head3 FORMAL SPECIFICATION

        run(args) = dispatch(args)                  if dispatch succeeds
        run(args) = 1 ∧ log(strip_location(error))  if it raises

=cut