checkpoint: continuiung writing the getting started guide

When creating the configuration file during the initialisation process
calculate the absolute path to the credentials file instead of the
relative path.

README.asciidoc

@@ -10,89 +10,21 @@
 == Overview
 
 Enbas is a https://docs.gotosocial.org/en/latest/[GoToSocial] client for your terminal written
-in https://go.dev[Go]. The project is in its experimental stages of development so bugs and breaking
+in https://go.dev[Go].
-changes may appear. Enbas has limited functionality at the moment and it is **not** recommended for use
+
-with your production GoToSocial servers.
+The project is in its early stages of development so expect bugs, breaking changes and limited functionality at this time
+It is **not** recommended for use this with your production GoToSocial servers.
 
 This project is licensed under the GNU General Public License V3 or later which you can view link:LICENSES/GPL-3.0-or-later.txt[here].
 
 === Repository mirrors
 
-- **Code Flow:** https://codeflow.dananglin.me.uk/apollo/enbas
+Enbas is primarily developed in Code Flow https://codeflow.dananglin.me.uk/apollo/enbas[here] with the `main` branch pushed to
-- **Codeberg:** https://codeberg.org/dananglin/enbas
+https://codeberg.org/dananglin/enbas[Codeberg] and https://github.com/dananglin/enbas[GitHub]
-- **GitHub:** https://github.com/dananglin/enbas
 
 == Installation
 
-=== Download
+(Moved)
-
-Pre-built binaries will be available on the release page on both Codeberg and GitHub when the first
-release is made.
-
-=== Build from source
-
-==== Requirements
-
-===== Go
-
-A minimum version of Go 1.22.0 is required for installing spruce.
-Please go https://go.dev/dl/[here] to download the latest version.
-
-===== Mage (Optional)
-
-The project includes mage targets for building and installing the binary.
-The main advantage of using mage over `go install` is that the build information is baked into the binary
-during compilation. You can visit the https://magefile.org/[Mage website] for instructions on how to install Mage.
-
-==== Install with mage
-
-You can install Enbas with Mage using the following commands:
-
-[source,console]
-----
-git clone https://github.com/dananglin/enbas.git
-mage install
-----
-
-By default Mage will attempt to install Enbas to `/usr/local/bin/enbas` which will most likely fail as you won't
-the permission to write to `/usr/local/bin/`. You will need to either run `sudo mage install`, or you can
-(preferably) change the install prefix to a directory that you have permission to write to using
-the `ENBAS_INSTALL_PREFIX` environment variable. For example:
-
-[source,console]
-----
-ENBAS_INSTALL_PREFIX=${HOME}/.local mage install
-----
-
-This will install Enbas to `~/.local/bin/enbas`.
-
-===== Environment variables you can use with Mage
-
-[%header,cols=2*]
-|===
-|Environment Variable
-|Description
-
-|`ENBAS_INSTALL_PREFIX`
-|Set this to your preferred the installation prefix (default: `/usr/local`).
-
-|`ENBAS_BUILD_REBUILD_ALL`
-|Set this to `1` to rebuild all packages even if they are already up-to-date.
-
-|`ENBAS_BUILD_VERBOSE`
-|Set this to `1` to enable verbose logging when building the binary.
-|===
-
-==== Install with go
-
-If your `GOBIN` directory is included in your `PATH` then you can install Enbas with Go.
-
-[source,console]
-----
-git clone https://github.com/dananglin/enbas.git
-cd enbas
-go install ./cmd/enbas
-----
 
 == Configuration
 
@@ -112,53 +44,6 @@ the current working directory.
 
 == Usage
 
-=== Check the build information
-
-You can view the application's version and build information using the `--version` flag.
-The build information is correctly displayed if you've downloaded the binary from Codeberg or GitHub,
-or if you've built it with Mage.
-
-[source,console]
-----
-$ enbas version --full
-Enbas
-  Version: v0.0.0-13-g26a909d
-  Git commit: 26a909d
-  Go version: go1.22.0
-  Build date: 2024-02-25T15:22:55Z
-----
-
-=== Check out the help documentation
-
-You can view the help documentation with the `--help` flag.
-You can also use this flag to view the help documentation for any of the commands.
-
-[source,console]
-----
-$ enbas --help
-SUMMARY:
-    enbas - A GoToSocial client for the terminal.
-
-VERSION:
-  v0.0.0-13-g26a909d
-
-USAGE:
-    enbas [flags]
-    enbas [command]
-
-COMMANDS:
-    login       login to an account on GoToSocial
-    show        print details about a specified resource
-    switch      switch to an account
-    version     print the application's version and build information
-
-FLAGS:
-    --help
-        print the help message
-
-Use "enbas [command] --help" for more information about a command.
-----
-
 === Log into your GoToSocial account
 
 Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial.
@@ -249,7 +134,7 @@ enbas show --type status --status-id 01HQE43KT5YEDN4RGMT7BC63PF
 
 == Inspirations
 
-This project was inspired from the following projects:
+This project was inspired by the following projects:
 
 * **madonctl:** https://github.com/McKael/madonctl[A Mastodon CLI client written in Go.]
 * **toot:** https://pypi.org/project/toot/[A Mastodon CLI and TUI written in Python.]

docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+## Summary
+
+In this guide we are going to log into an account on a private GoToSocial server.
+Follow along to log into your own account.
+
+## Your configuration directory
+
+Enbas uses Go's [os.UserConfigDir()](https://pkg.go.dev/os#UserConfigDir) function to calculate the location of your configuration directory.
+
+If you've set the `XDG_CONFIG_HOME` environment variable, the configuration directory will be set to `$XDG_CONFIG_HOME/enbas`.
+
+If this is not set, then:
+
+- on Linux the configuration directory will be set to `$HOME/.config/enbas`.
+- on Darwin (MacOS) the configuration directory will be set to `$HOME/Library/Application Support/enbas`.
+- on Windows the configuration directory will be set within the `%AppData%` directory.
+
+Alternatively you can use the `--config-dir` global flag to specify your configuration directory.
+
+## Generate your configuration file
+
+Run the `init` command to generate your configuration file.
+
+```bash
+enbas init
+```
+
+Use the `--config-dir` flag if you want to generate it in a specific directory
+
+```bash
+enbas --config-dir config init
+```
+
+You should now see a file called `config.json` in your configuration directory.
+Feel free to edit the file to your preferences (configuration documentation coming soon).
+
+For this 'Getting Started' guide you may want to specify your preferred browser in the configuration to allow Enbas to open the link to your instance's authorisation page. If you prefer to open the link manually then you can leave it blank.
+
+## Log into your GoToSocial account
+
+Enbas uses the Oauth2 authentication flow to log into your account on GoToSocial.
+
+```
+[WARNING]
+
+As of writing GoToSocial does not currently support scoped authorization tokens so even if we request read-only
+tokens, the application will be able to perform any actions within the limitations of your account
+(including admin actions if you are an admin).
+You can read more about this https://docs.gotosocial.org/en/latest/api/authentication/[here].
+```
+
+Follow the below steps to log into your account:
+
+1. Run the `login` command specifying the instance that you want to log into.
+    ```
+    enbas login --instance gts.enbas-demo.private
+    ```
+
+2. Enbas will send a registration request to your instance and receive a new client ID and secret that it needs for authentication.
+
+3. Enbas will then generate a link to the consent form for you to access in your browser and print it to your terminal screen along with a message explaining that you need to obtain the `out-of-band` token to continue.
+
+   The link will open in a tab in your preferred browser if you've specified it in your configuration, otherwise you can manually open it yourself.
+
+   If the browser tab doesn't open for you as expected you can still manually open it yourself.
+
+4. Once you've signed into GoToSocial on your browser, you will be informed that Enbas would like to perform actions on your behalf.
+If you're happy with this then click on the `Allow` button.
+   ![A screenshot of the consent form](/assets/images/consent_form.png "Consent Form")
+
+5. The `out-of-band` token from your instance will be displayed to you in your browser. Copy it and return to your terminal.
+
+6. Paste the token into the prompt and press `ENTER`.
+Enbas will then exchange the token for an access token which will be used to authentication to your instance on your behalf.
+
+7. Enbas will then verify the access token, save the credentials to the `credentials.json` file in your configuration directory,
+and inform you that you have successfully logged into your account.
+
+```
+$ enbas login --instance gotosocial-01.social.example
+
+You'll need to sign into your GoToSocial's consent page in order to generate the out-of-band token to continue with
+the application's login process. Your browser may have opened the link to the consent page already. If not, please
+copy and paste the link below to your browser:
+
+https://gotosocial-01.social.example/oauth/authorize?client_id=01RHK48N1KH9SFNH2VVZR414BJ&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&response_type=code
+
+Once you have the code please copy and paste it below.
+
+Out-of-band token: ZGJKNDA2YWMTNGEYMS0ZZJLJLWJHNDITM2IZYJJLNJM3YJBK
+Successfully logged into bobby@gotosocial-01.social.example
+```
+
+## View your account information

docs/install.md

@@ -0,0 +1,117 @@
+# Installation
+
+## Download
+
+Pre-built binaries will soon be available on the release page on both Codeberg and GitHub.
+
+## Build from source
+
+### Build requirements
+
+- **Go:** A minimum version of Go 1.22.0 is required for installing spruce.
+  Please go [here](https://go.dev/dl/) to download the latest version.
+
+- **Mage (Optional):** The project includes mage targets for building and installing the binary. The main
+  advantage of using mage over `go install` is that the build information is baked into the binary during
+  compilation. You can visit the [Mage website](https://magefile.org/) for instructions on how to install Mage.
+
+### Install with mage
+
+You can install Enbas with Mage using the following commands:
+
+```bash
+git clone https://github.com/dananglin/enbas.git
+mage install
+```
+
+By default Mage will attempt to install Enbas to `/usr/local/bin/enbas` which will most likely fail as you won't
+the permission to write to `/usr/local/bin/`. You will need to either run `sudo mage install`, or you can
+(preferably) change the install prefix to a directory that you have permission to write to using
+the `ENBAS_INSTALL_PREFIX` environment variable. For example:
+
+```bash
+ENBAS_INSTALL_PREFIX=${HOME}/.local mage install
+```
+
+This will install Enbas to `~/.local/bin/enbas`.
+
+The table below shows all the environment variables you can use when building with Mage.
+
+| Environment Variable     | Description                                                                  |
+|--------------------------|------------------------------------------------------------------------------|
+|`ENBAS_INSTALL_PREFIX`    | Set this to your preferred the installation prefix (default: `/usr/local`).  |
+|`ENBAS_BUILD_REBUILD_ALL` | Set this to `1` to rebuild all packages even if they are already up-to-date. |
+|`ENBAS_BUILD_VERBOSE`     | Set this to `1` to enable verbose logging when building the binary.          |
+
+### Install with go
+
+If your `GOBIN` directory is included in your `PATH` then you can install Enbas with Go.
+
+```bash
+git clone https://github.com/dananglin/enbas.git
+cd enbas
+go install ./cmd/enbas
+```
+
+## Verify the installation
+
+Type `enbas` from your terminal to verify that the installation was successful. You should see the help documentation.
+
+```bash
+$ enbas
+SUMMARY:
+    enbas - A GoToSocial client for the terminal.
+
+VERSION:
+    v0.1.0
+
+USAGE:
+    enbas [flags]
+    enbas [flags] [command]
+
+COMMANDS:
+    accept      Accept a request (e.g. a follow request)
+    add         Add a resource to another resource
+    block       Block a resource (e.g. an account)
+    create      Create a specific resource
+    delete      Delete a specific resource
+    edit        Edit a specific resource
+    follow      Follow a resource (e.g. an account)
+    init        Create a new configuration file in the specified configuration directory
+    login       Login to an account on GoToSocial
+    mute        Mute a resource (e.g. an account)
+    reject      Reject a request (e.g. a follow request)
+    remove      Remove a resource from another resource
+    show        Print details about a specified resource
+    switch      Perform a switch operation (e.g. switch logged in accounts)
+    unblock     Unblock a resource (e.g. an account)
+    unfollow    Unfollow a resource (e.g. an account)
+    unmute      Unmute a resource (e.g. an account)
+    version     Print the application's version and build information
+    whoami      Print the account that you are currently logged in to
+
+FLAGS:
+    --help
+        print the help message
+    --config-dir
+        Specify your config directory
+    --no-color
+        Disable ANSI colour output when displaying text on screen
+
+Use "enbas [command] --help" for more information about a command.
+```
+
+You can also view the application's version and build information using the `version` command.
+The build information is correctly displayed if you've downloaded the binary from Codeberg or GitHub,
+or if you've built it with Mage.
+
+```bash
+Enbas
+
+Version:    v0.1.0
+Git commit: c8892a6
+Go version: go1.22.4
+Build date: 2024-06-28T21:57:37Z
+```
+
+Once you have completed the installation proceed to the [Getting Started guide](./getting-started.md).

internal/config/config.go

@@ -71,7 +71,15 @@ func SaveDefaultConfigToFile(configDir string) error {
 	}
 	defer file.Close()
 
-	config := defaultConfig(configDir)
+	config := defaultConfig()
+
+	credentialsFilePath, err := utilities.AbsolutePath(defaultCredentialsConfigFile(configDir))
+	if err != nil {
+		return fmt.Errorf("unable to calculate the path to the credentials file: %w", err)
+	}
+
+	config.CredentialsFile = credentialsFilePath
+
 	encoder := json.NewEncoder(file)
 	encoder.SetIndent("", "    ")
 
@@ -86,11 +94,9 @@ func configFile(configDir string) string {
 	return filepath.Join(utilities.CalculateConfigDir(configDir), configFileName)
 }
 
-func defaultConfig(configDir string) Config {
+func defaultConfig() Config {
-	credentialsFilePath := defaultCredentialsConfigFile(configDir)
-
 	return Config{
-		CredentialsFile: credentialsFilePath,
+		CredentialsFile: "",
 		CacheDirectory:  "",
 		HTTP: HTTPConfig{
 			Timeout:      5,

internal/executor/login.go

@@ -100,7 +100,7 @@ func (l *LoginExecutor) Execute() error {
 		return fmt.Errorf("unable to save the authentication details: %w", err)
 	}
 
-	l.printer.PrintSuccess("Successfully logged into " + loginName + ".")
+	l.printer.PrintSuccess("You have successfully logged as " + loginName + ".")
 
 	return nil
 }

internal/utilities/absolute.go

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2024 Dan Anglin <d.n.i.anglin@gmail.com>
+//
+// SPDX-License-Identifier: GPL-3.0-or-later
+
+package utilities
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func AbsolutePath(path string) (string, error) {
+	if strings.HasPrefix(path, "~") {
+		homeDir, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("unable to get user's home directory; %w", err)
+		}
+
+		path = filepath.Join(homeDir, path[1:])
+	}
+
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return "", fmt.Errorf("unable to get the absolute path: %w", err)
+	}
+
+	return absPath, nil
+}