Update setup process and instructions

[adhilto]

🗣 Description

Modified the installation process and documentation per feedback.

Coauthered by @atuomit.

Goals of these changes:

• Change ./scubagoggles into a directory per For forward compatibility reasons .scubagoggles should be a directory and this config should be a file under that directory. The current config file should also be a file under that directory. #526.
• Resolve the usability concerns raised in Update the Download and Install guide intructions #531.
• Maintain the ability to specify custom default values for OPA path, output directory, and credentials path (added by Policy API Integration #499).
• Maintain the ability for users to run ScubaGoggles without the setup utility (Policy API Integration #499 maintained this capability, so this was just a question of not breaking it).

Specific changes:

• The "~ /.scubagoggles" file is now "~/.scubagoggles/userdefaults.json"
• The setup utility no longer prompts the user to input the OPA path, credentials path, or output path if not provided.
• The parameters for the setupt utility have been renamed for consistency with the parameters used for scubagoggles gws
• If not specified by the user, the OPA executable will be saved in ~/.scubagoggles/.
• If not specified by the user, ScubaGoggles will expect the credentials as ./credentials.json.
• If not specified by the user, ScubaGoggles will save the output in the current directory of the user calling ScubaGoggles.
• All of the above defaults can be changed at any time by the user using the setup utility.
• Documentation has been updated to reflect the above changes.

💭 Motivation and context

Closes #526.
Closes #531.

🧪 Testing

I recommend the reviewers start by following the README instructions as a new user would, specifically the 3 files listed under the "Installation" section of the README: https://github.com/cisagov/ScubaGoggles/blob/531-update-setup-instructions/README.md.

If you already have ScubaGoggles installed, first move the .scubagoggles file from your home directory. Since that was a text file and now is a folder, you will need to first move it before you can use the new setup util.

I performed the following tests:

1. Run "scubagoggles setup" from a clean slate, with no prexisting user defaults file
2. Run "scubagoggles setup" with a prexisting user defaults file
3. Run "scubagoggles setup" with a ~/.scubagoggles text file setup by v0.4
4. Run "scubagoggles setup -o [folder name]" with a folder that doesn't exist
5. Run "scubagoggles setup -o [folder name]" with a folder that does exist
6. Run "scubagoggles setup -o [folder name]" with a relative path
7. Run "scubagoggles setup -r [folder name]" with a folder that does exist
8. Run "scubagoggles setup -r [folder name]" with a folder that doesn't exist
9. Run "scubagoggles setup -r [folder name] -nd" with a folder that doesn't exist
10. Run "scubagoggles gws" when the opa folder is empty
11. Run "scubagoggles setup -r [folder name]" where [folder name] is actually a file not a folder
12. Run "scubagoggles setup -c [file name]" with a file that does exist
13. Run "scubagoggles setup -c [file name]" with a file that doesn't exist
14. Run "scubagoggles setup -c [file name] -nc" with a file that doesn't exist
15. Run "scubagoggles gws" without using setup util or cli args, verify that it fails and tells the user to provide credentials.
16. Run scubagoggles gws ... with ~/.scubagoggles as a text file from v0.4
17. Run "scubagoggles gws -h" without running the setup util first
18. Run "scubagoggles gws -h" after running the setup util
19. Run scubagoggles gws ... with a value for the creds file defined in the user defaults file, verify that creds file is used
20. Run scubagoggles gws ... with a value for the creds file defined in the user defaults file but override it with a config file
21. Run scubagoggles gws ... with a value for the creds file defined in the user defaults file but override it on the commandline
22. Run scubagoggles gws ... with cred path specified in the user defaults file that doesn't exist
23. Run scubagoggles gws ... with opa path specified in the user defaults file that doesn't exist
24. Run scubagoggles gws ... with output path specified in the user defaults file that doesn't exist
25. Run scubagoggles gws ... with paths specified in the user defaults file that don't exist but overwritten with good paths as cli args
26. Run scubagoggles setup when OPA exists in the path
27. Run scubagoggles gws when OPA exists in the path but not in the current directory or defined in the user defaults

✅ Pre-approval checklist

• This PR has an informative and human-readable title.
• Changes are limited to a single goal - eschew scope creep!
• If applicable, All future TODOs are captured in issues, which are referenced in the PR description.
• The relevant issues PR resolves are linked preferably via closing keywords.
• All relevant type-of-change labels have been added.
• I have read and agree to the CONTRIBUTING.md document.
• These code changes follow cisagov code standards.
• All relevant repo and/or project documentation has been updated to reflect the changes in this PR.
• Tests have been added and/or modified to cover the changes in this PR.
• All new and existing tests pass.

✅ Pre-merge Checklist

• This PR has been smoke tested to ensure main is in a functional state when this PR is merged.
• Squash all commits into one PR level commit using the Squash and merge button.

✅ Post-merge Checklist

• Delete the branch to clean up.
• Close issues resolved by this PR if the closing keywords did not activate.

[snarve]

Discussed with Alden on some of the steps in the Development guide that might need some tweaking.

[atuomit]

I saw that in the updates to the development guide, the option to run "python scuba.py" was removed. I think its fine if we want developers to install ScubaGoggles instead of just running the code directly but I think it should have a note to remind developers that in this method, they needs to rerun "python -m pip install ." to apply any code changes.

[adhilto]

I saw that in the updates to the development guide, the option to run "python scuba.py" was removed. I think its fine if we want developers to install ScubaGoggles instead of just running the code directly but I think it should have a note to remind developers that in this method, they needs to rerun "python -m pip install ." to apply any code changes.

Actually the change there is pretty cool. If you run pip with the -e flag, you no longer will need to re-install any time you change something 🎉

Also I did include this note, is that sufficient?

[atuomit]

Oh, sorry! Didn't notice the note about the flag. Yes, that looks great!

[snarve]

The instructions for service account are missing the steps to enable the API scope

Link for service account setup: https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/ServiceAccount.md

The above screen capture is from the OAuth instructions page: https://github.com/cisagov/ScubaGoggles/blob/main/docs/authentication/OAuth.md

Both pages are also missing instructions on adding the Cloud Identity API

[adhilto]

@rlxdev @snarve I believe I have addressed all your feedback, I'm ready for another round of reviews.

[snarve]

In this section, after the download the project part, the note to the Development guide should appear. The part regarding the .whl file can be moved in the Installing ScubaGoggles section where there is more information about the .whl file.

Also, the to 'download click here' points to the release, so the Development Guide note can be moved to the top.

[snarve]

Looks great!
Just added one comment for a minor update.

[snarve]

Great Job Alden!