Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(cli): Added docs for the CLI package #329

Merged
merged 2 commits into from
Jul 7, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/cli/src/commands/init.command.ts
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ export default class InitCommand extends BaseCommand {
{
short: '-o',
long: '--overwrite',
description: 'Overwrite existing configuration'
description: 'Overwrite existing configuration',
defaultValue: false
}
]
}
Expand Down
5 changes: 4 additions & 1 deletion docs/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,14 @@
- [Design of our code](contributing-to-keyshade/design-of-our-code/README.md)
- [Organization of code](contributing-to-keyshade/design-of-our-code/organization-of-code.md)
- [API](contributing-to-keyshade/design-of-our-code/api.md)
- [Integrations](contributing-to-keyshade/design-of-our-code/integrations.md)
- [CLI](contributing-to-keyshade/design-of-our-code/cli.md)
- [Web](contributing-to-keyshade/design-of-our-code/web.md)
- [Integrations](contributing-to-keyshade/design-of-our-code/integrations.md)
- [Prerequisites](contributing-to-keyshade/prerequisites.md)
- [Environment Variables](contributing-to-keyshade/environment-variables.md)
- [Setting things up](contributing-to-keyshade/setting-things-up.md)
- [Running things locally](contributing-to-keyshade/running-things-locally/README.md)
- [Running the API](contributing-to-keyshade/running-things-locally/running-the-api.md)
- [Running the Web](contributing-to-keyshade/running-things-locally/running-the-web.md)
- [Running the CLI](contributing-to-keyshade/running-things-locally/running-the-cli.md)
- [API Testing](contributing-to-keyshade/running-things-locally/api-testing.md)
4 changes: 3 additions & 1 deletion docs/contributing-to-keyshade/design-of-our-code/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@ When it comes to developing for us, we follow very strict norms! From proper ind
## Compilation of designs

- [Organization Of Code](organization-of-code.md)

* [API](api.md)
* [Integrations](integrations.md)
* [Web](web.md)
* [CLI](cli.md)
* [Integrations](integrations.md)
84 changes: 84 additions & 0 deletions docs/contributing-to-keyshade/design-of-our-code/cli.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
description: Design of our CLI
---

# CLI

The CLI is what you use to connect your applications to keyshade to utilize the configurations. Apart from that, you can also use the CLI to manage your configurations, workspace, and other things. In this document, we will cover how we have developed our CLI, talk about the infrastructure, and how you can start contributing to it.

## Stack

We have a very simple stack for our CLI:

- **NodeJS** as the base
- **Commander** as the CLI framework
- **Clack** for interactive prompts

## Structure

We are following the principles of OOP to design a clean and extendible CLI. The current architecture allows us to easily build upon the existing system to add new features.

### Folder structure

- **commands**: Contains the command files that are used by the CLI
- **utils**: Contains utility functions that are used across the CLI
- **types**: Contains the types that are used across the CLI
- **http**: Contains the HTTP client that is used to interact with the keyshade API

### The `BaseCommand` class

The `BaseCommand` class is the parent class for all the commands that are used by the CLI. It contains common methods that are used by all the commands. You can find it in `src/commands/base.command.ts`. The objects of the subclasses created are primarily tied up in the `COMMANDS` variable in `index.ts`.

#### Methods

It is an abstract class with only two abstract methods:

- `getName`: This method returns the name of the command
- `getDescription`: This method returns the description of the command

The rest of the commands are optional and can be overridden as per the requirement.

#### Creating a new command

Whenever you try to develop a command, you would need to take the following steps:

- Create a new file in the `commands` folder with this name: `<command-name>.command.ts`
- Create a new class in that file with this format: `export class <CommandName>Command extends BaseCommand`
- Implement the abstract methods `getName` and `getDescription` in the class
- Next up, decide on the other fields that you would like to override from the `BaseCommand` class. It is highly recommended to go through the `BaseCommand` class to understand the methods that you can override.
- If you think you will need to create any more subcommands, create a folder with the name of the command in the `commands` folder and follow the same steps as above. Once done, you would need to tie up those commands by overriding the `getSubCommands` function in the parent command.
- Once you have finished working on the commands, you would need to add the command to the `COMMANDS` variable in `index.ts`.

#### The `action` function

This function is at the heart of the CLI. Any and every action performed by the commands are done inside this function. It is recommended to keep the `action` function as clean as possible and move the logic to other `private` functions if needed.

The action function accepts just a single argument with the type `CommandActionData`:

```typescript
export interface CommandActionData {
options: Record<string, any>
args: string[]
}
```

The arguments and options used by the command are passed to the `action` function. You can access them using `data.options` and `data.args`.

Consider this command: `ks profile update main --name "New Name"`. In this command, `main` is the argument and `--name "New Name"` is the option. You can access the argument using `data.args[0]` and the option using `data.options.name`. The code implementation will look something like this:

```typescript
// ... snip
public async action({ options, args }: CommandActionData): Promise<void> {
const profileName = args[0]
const { name } = options

// Your logic here
}
// ... snip
```

#### Best practices

- Please ensure that you don't stash too much functionality inside the `action`. Use self-explanatory private function names and move the logic to those functions.
- We use `fetch` for making HTTP requests. Please ensure that you use the HTTP client from `src/http` to make requests.
- Whenever you are creating any HTTP request, please add the API request to the `src/http/<command>.ts` file. This will help in maintaining the codebase and will make it easier for others to understand the code.
10 changes: 9 additions & 1 deletion docs/contributing-to-keyshade/design-of-our-code/web.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,7 @@
---
description: Design of our Web package
---

# Web

The web application is responsible for serving the homepage, providing users with access to its content and functionality, the stacks, and things you should know before you get started with it!
Expand All @@ -21,23 +25,27 @@ The web application is responsible for serving the homepage, providing users wit
├── public
├── src
| ├── app
| ├── components
| ├── components
| └── utils
└── config_files
```

### web

The main directory that contains all parts of the web app.

#### public

Contains static files and assets.

#### src

Contains the source code of the app.

- **app**: Holds the main pages and settings for the app.
- **components**: Reusable pieces used in the app.
- **utils**: Helper tools and functions that support the app.

#### config_files

Contains configuration files for the app.
Original file line number Diff line number Diff line change
Expand Up @@ -11,4 +11,6 @@ This document (and the sub-series) guides you on how you can run and test each o
You can pick up any of these topics from the following and start with it.

- [Running the API](running-the-api.md)
- [Running the Web](running-the-web-app.md)
- [Running the CLI](running-the-cli.md)
- [API Testing](api-testing.md)
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,25 @@ description: Get to know how you can develop the API!

The API resides in the `apps/api` directory. It is a NestJS project. To run the API locally, do the following:

* Get the database and cache up and running:
- Get the database and cache up and running:

```bash
docker compose up -d
```

* Generate the prisma types:
- Generate the prisma types:

```bash
pnpm run db:generate-types
```

* Deploy the migrations:
- Deploy the migrations:

```bash
pnpm run db:deploy-migrations
```

* Start the server in development mode:
- Start the server in development mode:

```bash
pnpm run dev:api
Expand All @@ -47,6 +47,7 @@ pnpm run e2e:api
```

You can also skip these first two commands and perform the unit and e2e tests at the same time with:

```bash
pnpm run test:api
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
---
description: Get to know how you can develop the CLI!
---

# Running the CLI

You can get started with developing the CLI using the following steps:

- Start developing the code

- Run the API:

```bash
docker compose up -d
pnpm dev:api
```

- Run the build command to continuously build the code:

```bash
cd apps/cli && pnpm build:cli
```

- Run the CLI:

```bash
cd apps/cli && node dist/index.js <command> [subcommand] <arguments> [options]
```