diff --git a/apps/cli/src/commands/init.command.ts b/apps/cli/src/commands/init.command.ts index e64879a4..b528ca11 100644 --- a/apps/cli/src/commands/init.command.ts +++ b/apps/cli/src/commands/init.command.ts @@ -36,7 +36,8 @@ export default class InitCommand extends BaseCommand { { short: '-o', long: '--overwrite', - description: 'Overwrite existing configuration' + description: 'Overwrite existing configuration', + defaultValue: false } ] } diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 30f62afa..fff3f765 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -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) diff --git a/docs/contributing-to-keyshade/design-of-our-code/README.md b/docs/contributing-to-keyshade/design-of-our-code/README.md index a3d8c36f..a814becb 100644 --- a/docs/contributing-to-keyshade/design-of-our-code/README.md +++ b/docs/contributing-to-keyshade/design-of-our-code/README.md @@ -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) diff --git a/docs/contributing-to-keyshade/design-of-our-code/cli.md b/docs/contributing-to-keyshade/design-of-our-code/cli.md new file mode 100644 index 00000000..5e20bf6d --- /dev/null +++ b/docs/contributing-to-keyshade/design-of-our-code/cli.md @@ -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.ts` +- Create a new class in that file with this format: `export class 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 + 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 { + 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/.ts` file. This will help in maintaining the codebase and will make it easier for others to understand the code. diff --git a/docs/contributing-to-keyshade/design-of-our-code/web.md b/docs/contributing-to-keyshade/design-of-our-code/web.md index 6c77eafc..ce514fb4 100644 --- a/docs/contributing-to-keyshade/design-of-our-code/web.md +++ b/docs/contributing-to-keyshade/design-of-our-code/web.md @@ -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! @@ -21,18 +25,21 @@ 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. @@ -40,4 +47,5 @@ Contains the source code of the app. - **utils**: Helper tools and functions that support the app. #### config_files + Contains configuration files for the app. diff --git a/docs/contributing-to-keyshade/running-things-locally/README.md b/docs/contributing-to-keyshade/running-things-locally/README.md index edfe8218..b2bb912d 100644 --- a/docs/contributing-to-keyshade/running-things-locally/README.md +++ b/docs/contributing-to-keyshade/running-things-locally/README.md @@ -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) diff --git a/docs/contributing-to-keyshade/running-things-locally/running-the-api.md b/docs/contributing-to-keyshade/running-things-locally/running-the-api.md index 52c8b03e..ebadd0bd 100644 --- a/docs/contributing-to-keyshade/running-things-locally/running-the-api.md +++ b/docs/contributing-to-keyshade/running-things-locally/running-the-api.md @@ -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 @@ -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 ``` diff --git a/docs/contributing-to-keyshade/running-things-locally/running-the-cli.md b/docs/contributing-to-keyshade/running-things-locally/running-the-cli.md new file mode 100644 index 00000000..fe4d93ac --- /dev/null +++ b/docs/contributing-to-keyshade/running-things-locally/running-the-cli.md @@ -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 [subcommand] [options] + ```