Skip to content

Latest commit

 

History

History
105 lines (83 loc) · 4.91 KB

source-code.md

File metadata and controls

105 lines (83 loc) · 4.91 KB
Raw

Source Code Overview

A brief overview of the clide-js repo.

The repo is a yarn Workspaces monorepo using Turborepo. Top level commands are "turbo" scripts which are added to the root package.json and configured in turbo.json.

Top level commands are run just like any other yarn project:

yarn <script-name>

Replace <script-name> with the script name from package.json.

To run a command from a workspace (package) located inside the monorepo:

yarn workspace <package-name> <script-name>

Replace <package-name> with the package name located in the package's package.json.

Folder Organization

.github/ # actions and workflows for github
.vscode/ # vscode project settings
assets/ # assets for the README.md
examples/ # example CLIs built with clide-js
notes/ # misc notes
packages/ # package directories
├─ clide-js/ # core package
├─ clide-plugin-command-menu/ # a plugin to prompt users for missing subcommands
├─ extras/ # utilities from CLIs I've written in the past that might get used later.
├─ tsconfig/ # shared tsconfig

The 2 published packages are clide-js and clide-plugin-command-menu

Clide-JS Source Code

The clide-js package contains the core code for the Clide-JS framework.

Folder Organization

src/
├─ cli/ # used as a sandbox to test features, will eventually be a real CLI
├─ core/ # the main code for clide-js
├─ plugins/ # built-in plugins that enable optional features like help
├─ utils/ # utilities used throughout, should not reference any code outside utils
test/
├─ mocks/ # mocking code
├─ src/ # tests for code in src
.gitignore
package.json
tsconfig.json
tsup.config.ts # build config
typedoc.json # docs generator config
vitest.config.ts # testing config

Everything revolves around the context module which acts as the orchestrator for the entire command lifecycle, preparing the command for execution, and providing a central method for throwing errors and exiting the process.

It makes use of the other modules in core for most of it's functionality:

  • hooks: Contains the HooksEmitter which is used by Context and State to call hooks from plugins during lifecycle events.
  • client: Contains a Client class for logging and prompting. I would like to build this out more to work with different stdin, stdout, and stderr settings.
  • resolve: Contains functions to locate and import command modules based on a command string.
  • state: Contains the State class which manages the state of command execution with mechanisms to progress through the steps, handle state transition, and manage the lifecycle of shared command data.

The state module uses options-getter to create an OptionsGetter for use in command handlers during execution. The OptionsGetter is an object with methods on it for every option with type safe keys for the option key and it's aliases. These methods are used to dyanamically fetch option values with optional prompt fallbacks.

The help module generates help text for a command context and is used by the built-in help plugin.

The run module contains the run function which is the primary entry to framework, used in the bin file of CLIs. It offers a simple unified API for running a CLI with the Clide-JS framework. It manages registering hooks, creating a Context instance, adding options, preparing and executing the context, and catching errors.

Lastly in core, the command module contains a factory function for creating type safe command modules. These are used in the command files of CLIs and should be their default export.