fix(files): files:scan error ouput when user_id is not found + return correct exit status on error

[joshtrichards]

Summary

Note: This looks like a lengthier change than it really is due to moving the location of execute() for readability.

• Fixes occ files:scan misinterprets wrong path as username #27031 (improves error output when user_id in path is invalid)
• Fixes occ output not quiet when it should be, exit code not proper #27029 (adds exit status 1 if any errors occur during a run) [lines 154-156]
• Refactor: moves execute() function location to immediately after configure() for readability / consistency
• Expands occ command description and adds help
• Clarifies/streamlines language of argument/option explanations + uses capital letters at the beginning (to match rest of Command output)

TODO

• Determine whether exit code addition means this can't be backported (or whether it's a non-event since it's technically correcting a bug and/or adjusting undocumented behavior)

Notes

There are two behavior changes here to be aware of (in order order of probably significance in terms of being classified as a "breaking change"):

Exit code

Previously even where there were errors the exit code (i.e. echo $?) was still 0. Now any errors mean the code will be 1.

Output is slightly different when user_id is not found (e.g. see #27031 for existing behavior):

Now it is:

www-data@83e3407f887c:~/html$ ./occ files:scan -p "/a"
User 1 out of 1 not found (a)
+---------+-------+-----+---------+---------+--------+--------------+
| Folders | Files | New | Updated | Removed | Errors | Elapsed time |
+---------+-------+-----+---------+---------+--------+--------------+
| 0       | 0     | 0   | 0       | 0       | 1      | 00:00:00     |
+---------+-------+-----+---------+---------+--------+--------------+

Output

Output of occ files with this PR:

Available commands for the "files" namespace:
[...]  
  files:repair-tree                Try and repair malformed filesystem tree structures
  files:scan                       Scans the filesystem for new files and updates the file cache
  files:scan-app-data              rescan the AppData folder
[...]

Output of occ files:scan --help with this PR:

Description:
  Scans the filesystem for new files and updates the file cache

Usage:
  files:scan [options] [--] [<user_id>...]

Arguments:
  user_id                                      Rescan all files of the specified user(s)

Options:
      --output[=OUTPUT]                        Output format (plain, json or json_pretty, default is plain) [default: "plain"]
  -p, --path=PATH                              Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters.
      --generate-metadata[=GENERATE-METADATA]  Generate metadata for all scanned files; if specified only generate for named value. [default: ""]
      --all                                    Rescan all files of all known users
      --unscanned                              Only scan files which are marked as not fully scanned
      --shallow                                Do not scan folders recursively
      --home-only                              Only scan the home storage, ignoring any mounted external storage or share
  -h, --help                                   Display help for the given command. When no command is given display help for the list command
  -q, --quiet                                  Do not output any message
  -V, --version                                Display this application version
      --ansi|--no-ansi                         Force (or disable --no-ansi) ANSI output
  -n, --no-interaction                         Do not ask any interactive question
      --no-warnings                            Skip global warnings, show command output only
  -v|vv|vvv, --verbose                         Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Help:
  You can rescan all files or only those of select user(s) or a select path. Statistics will be shown at the end of the scan by default.

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)

[joshtrichards]

Suggested change

	'Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters; the user_id is determined from the path.'
	'Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters.'

[artonge]

Maybe do not move the execute method to ease the review, or do that in a different commit :)

[artonge]

Maybe more explicit, as it does not only detect new files.

Suggested change

	->setDescription('Scans the filesystem for new files and updates the file cache')
	->setDescription('Scans the filesystem and updates the file cache acording to the detected additions, deletions and updates.')