3. Where to place your code

How do I Get my Enhancements into the Kui Code Base?

Now that you have decided how to wish to enhance Kui, this page covers where to place your code. If you haven't yet decided what kinds of enhancements you need, here is a quick reminder of the possibilities. You may enhance Kui via:

• New commands that for example fetch and return a data model. This could be a CRUD command against your API servers, such as kubectl get pods reads out data from the Kubernetes apiserver.
• Decoration of models returned by existing commands. For example, you may wish to augment the Pod model with an additional "mode" so that users will see a new way to inspect the details of pod resources.

Once you have sized up your enhancement strategy, you will want to start coding. Kui enhancements are always placed in plugins. You can see the existing plugins here: e.g. plugin-kubectl houses the Kubernetes enhancements, and plugin-bash-like houses the enhancements that allow Kui to interact with an underlying PTY.

Where should you place your code, so that you can shape and debug your enhancements? Here you have several options, ranging in complexity.

Option 1: Use plugin-skeleton (a good option for quick prototyping)

If you want to prototype your solution, you may place your code in plugin-skeleton.

	I want to add a New Command	I want to Decorate models returned by an existing Command
1)	consult this page for help with writing your command handler	consult this page for help with model decoration
2)	place that code into plugin-skeleton/src/plugin.ts	place that code into plugin-skeleton/src/preload.ts
3)	re-run npm start from the top-level of Kui

Example of adding a command that returns string

Let us follow this recipe for a very simple example. Say you wish Kui to respond to the command-line > hello world with a string Hello!. This is a New Command style of enhancement. As such, you would place the following code in plugin-skeleton/src/plugin.ts:

import { Registrar } from '@kui-shell/core'

export default async ({ listen }: Registrar) => {
  // this line routes a simple command handler to the command line "hello world"
  listen('/hello/world', () => 'Hello!')
}

Then, after restarting Kui via npm start, you should be able to execute the command hello world and see the expected string response. For more realistic and complex command, you probably will want to factor the command handler (() => 'Hello') into a separate file, and have it respond to command line positional and optional parameters. Consult the Commands documentation for more details.

Option 2: Isolate enhancements in a subdirectory of an existing plugin

If your enhancements are naturally related to the enhancements provided by an existing plugin, it makes sense to avoid creating a new top-level plugin directory. This allows the close relationship to be manifest in the directory structure. For example, plugin-kubectl has subdirectories for helm and krew.

Details coming soon

Option 3: Create a new top-level plugin directory

If your enhancements provide a novel perspective for Kui, then you should create a new top-level plugin directory.

Details coming soon