Enable themes

[AllanOricil]

With this feature developers will be able to create custom color themes for their CLI.

obs: disregard the --json I added in the pictures below

BEFORE

AFTER

---

A theme is enabled when:

• there is a json file called theme in ~/.config/data/<CLI>/theme.json
• <CLI>_DISABLE_THEME env var is not set

All theme colors are optional

LIGHT THEME EXAMPLES

---

Configurable Tokens

Colors are set with the values from ~/.config/<CLI>/theme.json file, if one is present. Colors can be set with Hex and RGB color codes strings, which are converted to colors using the color package.

{
       "alias" : "red",
       "bin" : "rgb(255, 255, 255)",
       "command" : "#45C65A",
       "commandSummary" : "#FFFFFF",
       "dollarSign" : "#FFFF00",
       "flag" : "#45C65A",
       "flagDefaultValue" : "#1AB9FF",
       "flagOptions" : "#45C65A",
       "flagRequired" : "#FE5C4C",
       "flagSeparator" : "#FFFFFF",
       "flagType" : "#0EAEE8",
       "sectionDescription" : "#FFFFFF",
       "sectionHeader" : "#FFFF00",
       "topic" : "#45C65A",
       "version" : "#45C65A"
}

In the following pictures you can understand the regions each token affect.

alias

bin

command

commandSummary

dollarSign

flag

flagDefaultValue

flagOptions

flagRequired

flagSeparator

flagType

NOT IMPLEMENTED YET.

It depends on a new attribute called "typeLabel" which has to be added to the flag configuration. Without allowing CLI developers to specify a custom label for the types of their flags, like filePath, users would only see "boolean | option" which is the value from flag.type.

sectionDescription

sectionHeader

topic

version

[AllanOricil]

Some tests are failing and I have not write any tests for my changes, but I'm ready for a review since the feature is mostly done and I need to know if there are bugs and your opinion on this. I have not tested few sections like: ARGUMENTS, DESCRIPTION, ALIASES,EXAMPLES and FLAG DESCRIPTIONS. How can I test if they are rendered properly?

[AllanOricil]

Using the Heroku CLI, I found that the DESCRIPTION, ALIASES, ARGUMENTS and EXAMPLES sections aren't working well, . I'm going to fix it, now that I have means to test it. But I could not find a command that displays the FLAG DESCRIPTIONS section. It would be good if you could help me to find a CLI or command that has it.

[mdonnalley]

@AllanOricil Great work 🏆

My biggest concern here is that users will have different terminal themes that would conflict with the configured theme. CLI developers would need to configure a theme that works on most terminal themes, which would be a challenging task.

I wonder if this should be something that we defer to users? Instead of looking in the CLI's package.json, oclif/core could look for a config file on the users machine. That would allow users to have colorful help without forcing them to use a specific terminal theme that works with it.

What do you think?

[mdonnalley]

@AllanOricil

Works for me if I do this in interfaces/config.ts

import * as Color from 'color'

export function parseTheme(untypedTheme: Record<string, string>): Theme {
  return Object.fromEntries(
    Object.entries(untypedTheme)
      .filter(([key]) => THEME_KEYS.includes(key))
      // eslint-disable-next-line new-cap
      .map(([key, value]) => [key, new Color.default(value)]),
  )
}

and this in help/util.ts

import * as Color from 'color'

[AllanOricil]

/@types/color/index"' can only be default-imported using the 'esModuleInterop' flag

fixed

[mdonnalley]

Just a few small things and then I'll approve.

[mdonnalley]

const theme = this.scopedEnvVarTrue('DISABLE_THEME') ? undefined : await safeReadJson<Record<string, string>>(themeFilePath)

That way you don't have to use as when passing it to parseTheme

[AllanOricil]

@mdonnalley

fixed at 00a6ccd

Could you tell me if you agree with what I did. I removed enableTheme from config.

[mdonnalley]

@AllanOricil I'm going to merge this into a separate feature branch so that we can run all the integration tests before merging. I'm taking a vacation tomorrow so I would expect to get this merged into main early next week

[AllanOricil]

@mdonnalley thank you for all the help 👍