Interactive Mode: Follow step-by-step guides from your terminal!

[DavidHancu]

Nothing makes for a better onboarding experience than a try-it-yourself command that allows you to follow any tutorial on the official documentation using an intuitive step-by-step wizard.

Implementation Notes

The way this would work is by having a JSON manifest saved in a GitHub repository with the name for the guide. When the user specifies the guide name, the corresponding manifest would be downloaded from GitHub and ran.

Manifest Format

A guide manifest is a JSON object that contains two properties: $manifest and steps. This section will go in-depth for each property of this object. An example of such format can be found here: prisma-util/getting-started.json.

The $manifest object

The $manifest object allows us to set metadata for this guide. One special property that this object can hold is the assets array.

The assets array

The assets array is a string array containing operations that adhere to the Asset Operations Format. These operations will be ran if the user agrees to download the files needed for the guide. They are ran sequentially.

The steps array

The steps array provides a way of defining tutorial steps that the user can follow. These steps are ran sequentially and can be of three types: command, editFile and removeFile.

Regardless of which type a step has, it is imperative that it declares a text property that tells the Interactive CLI how to render this step. This text is an array of arrays of Text Blocks.

Each array inside of the text array represents a new line.

Based on the type for each step, there are these required configurations:

For command

• allowedCommand: Because we don't want the Interactive CLI to allow users to run every commands, we can use this property to restrict them to only the command necessary for this step.
• displayPath: The path to be displayed. This path will not change the current working directory for the command, but it used as a visual indicator for the user.
• cwd: Change the current workind directory for the command. This path is relative to the starting location for the tutorial.
• changeEnv: An object that allows the step to modify the environment variables passed to the child process of this command.

For removeFile

• path: The path to the file to remove. The Interactive CLI will enforce this path, meaning that the user won't be able to proceed until this file has been deleted.

Asset Operations Format

There are two operations that you can do: download files and create directories.

Creating directories

The format for a directory creation operation is mkdir directory/name. The path to the directory will be relative from the current working directory.

Downloading files

Files can be downloaded using the from/path as to/path operation. This operation resolves the from/path from the root of the GitHub repository and saves the file to to/path which is relative to the current working directory.

Text Blocks

Text Blocks allow certain pieces of text to either be highlighted in a different color or just be a normal string. To define a colored text block, you'd have to create an object with two properties: color and text. A Text Block can either be a string or an object with the two properties.

The text property

The text property will contain the text that will be colored.

The color property

The color property is a string denoting a key of either chalk or gradient-string that specifies which color should be used for a Text Block.

Examples

I've implemented such a CLI in Prisma Util and I was wondering if it was possible to implement it here as well. It's very intuitive to use, all it requires is just two commands:

npm i prisma-util@latest
npx prisma-util interactive --tutorial getting-started

I imagine that a wizard like this would be greatly appreciated by new users trying out the quickstart guide from the Prisma documentation.

Final Words

I want to contribute to this project with this idea, assuming that you green-light this issue.