feat: help utilities

.circleci/config.yml

@@ -26,6 +26,7 @@ workflows:
           github-release: true
           requires:
             - release-management/test-package
+          tag: latest
   dependabot-automerge:
     triggers:
       - schedule:

.editorconfig

@@ -0,0 +1,11 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false

.eslintignore

@@ -0,0 +1 @@
+/lib

.eslintrc

@@ -0,0 +1,20 @@
+{
+  "extends": [
+    "oclif",
+    "oclif-typescript"
+  ],
+  "rules": {
+    "unicorn/import-style": "off",
+    "node/no-missing-import": "off",
+    "unicorn/consistent-destructuring": "off",
+    "unicorn/prefer-module": "off",
+    "unicorn/prefer-array-some": "off",
+    "unicorn/prefer-string-trim-start-end": "off",
+    "unicorn/prefer-node-protocol": "off",
+    "unicorn/no-array-for-each": "off",
+    "unicorn/no-useless-undefined": "off",
+    "unicorn/prefer-number-properties": "off",
+    "unicorn/consistent-function-scoping": "off",
+    "node/no-missing-require": "off"
+  }
+}

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.js text eol=lf
+*.ts text eol=lf

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @heroku/cli

.github/dependabot.yml

@@ -0,0 +1,17 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    versioning-strategy: increase
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"
+    open-pull-requests-limit: 100
+    pull-request-branch-name:
+      separator: "-"
+    ignore:
+      - dependency-name: "typescript"
+      - dependency-name: "fs-extra"
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]

.gitignore

@@ -0,0 +1,8 @@
+*-debug.log
+*-error.log
+/.nyc_output
+/coverage
+/coverage.lcov
+/lib
+/node_modules
+/tmp

.mocharc.json

@@ -0,0 +1,13 @@
+{
+  "require": [
+    "test/helpers/init.js",
+    "ts-node/register",
+    "source-map-support/register"
+  ],
+  "watch-extensions": [
+    "ts"
+  ],
+  "recursive": true,
+  "reporter": "spec",
+  "timeout": 60000
+}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Salesforce.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1 +1,11 @@
-# help
+@oclif/help
+===========
+
+**This library has been replaced by [@oclif/core](https://github.com/oclif/core) and is now in maintenance mode. We will only consider PRs that address security concerns.**
+
+standard help for oclif
+
+[![Version](https://img.shields.io/npm/v/@oclif/help.svg)](https://npmjs.org/package/@oclif/help)
+[![CircleCI](https://circleci.com/gh/oclif/help/tree/main.svg?style=svg)](https://circleci.com/gh/oclif/help/tree/main)
+[![Downloads/week](https://img.shields.io/npm/dw/@oclif/help.svg)](https://npmjs.org/package/@oclif/help)
+[![License](https://img.shields.io/npm/l/@oclif/help.svg)](https://github.com/oclif/help/blob/main/package.json)

package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@oclif/help",
+  "description": "standard help for oclif",
+  "version": "1.0.0",
+  "author": "Salesforce",
+  "bugs": "https://github.com/oclif/help/issues",
+  "dependencies": {
+    "@oclif/config": "1.18.2",
+    "@oclif/errors": "1.3.5",
+    "chalk": "^4.1.2",
+    "indent-string": "^4.0.0",
+    "lodash": "^4.17.21",
+    "string-width": "^4.2.0",
+    "strip-ansi": "^6.0.0",
+    "widest-line": "^3.1.0",
+    "wrap-ansi": "^6.2.0"
+  },
+  "devDependencies": {
+    "@oclif/command": "^1.8.13",
+    "@oclif/dev-cli": "1.26.9",
+    "@oclif/plugin-legacy": "1.2.6",
+    "@oclif/plugin-plugins": "1.10.10",
+    "@oclif/test": "1.2.9",
+    "@types/chai": "^4.1.7",
+    "@types/lodash": "^4.14.176",
+    "@types/mocha": "^8.0.0",
+    "@types/node": "^14.0.14",
+    "@types/strip-ansi": "^5.2.1",
+    "@types/wrap-ansi": "^8.0.1",
+    "chai": "^4.2.0",
+    "eslint": "7.32.0",
+    "eslint-config-oclif": "^3.1.0",
+    "eslint-config-oclif-typescript": "^0.2.0",
+    "globby": "^11.0.1",
+    "mocha": "^8.2.1",
+    "nock": "^13.0.0",
+    "sinon": "^10.0.0",
+    "ts-node": "^9.1.1",
+    "typescript": "3.8.3"
+  },
+  "engines": {
+    "node": ">=8.0.0"
+  },
+  "files": [
+    "/lib"
+  ],
+  "homepage": "https://github.com/oclif/help#readme",
+  "keywords": [
+    "oclif"
+  ],
+  "license": "MIT",
+  "main": "./lib/index.js",
+  "oclif": {
+    "bin": "oclif",
+    "devPlugins": [
+      "@oclif/plugin-plugins",
+      "@oclif/plugin-legacy"
+    ]
+  },
+  "scripts": {
+    "build": "rm -rf lib && tsc",
+    "lint": "eslint . --ext .ts --config .eslintrc",
+    "posttest": "yarn lint",
+    "prepublishOnly": "yarn run build",
+    "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "version": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0 && git add CHANGELOG.md",
+    "pretest": "yarn build --noEmit && tsc -p test --noEmit"
+  },
+  "types": "./lib/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oclif/help.git"
+  }
+}

src/_test-help-class.ts

@@ -0,0 +1,20 @@
+// `getHelpClass` tests require an oclif project for testing so
+// it is re-using the setup here to be able to do a lookup for
+// this sample help class file in tests, although it is not needed
+// for @oclif/plugin-help itself.
+
+import {HelpBase} from '.'
+
+export default class extends HelpBase {
+  showHelp() {
+    console.log('help')
+  }
+
+  showCommandHelp() {
+    console.log('command help')
+  }
+
+  getCommandHelpForReadme() {
+    return 'help for readme'
+  }
+}

src/command.ts

@@ -0,0 +1,164 @@
+import * as Config from '@oclif/config'
+import * as chalk from 'chalk'
+import indent = require('indent-string')
+import stripAnsi = require('strip-ansi')
+
+import {HelpOptions} from '.'
+import {renderList} from './list'
+import {castArray, compact, sortBy, template} from './util'
+
+const {
+  underline,
+  bold,
+} = chalk
+let {
+  dim,
+} = chalk
+
+if (process.env.ConEmuANSI === 'ON') {
+  dim = chalk.gray
+}
+
+const wrap = require('wrap-ansi')
+
+export default class CommandHelp {
+  render: (input: string) => string
+
+  constructor(public command: Config.Command, public config: Config.IConfig, public opts: HelpOptions) {
+    this.render = template(this)
+  }
+
+  generate(): string {
+    const cmd = this.command
+    const flags = sortBy(Object.entries(cmd.flags || {})
+    .filter(([, v]) => !v.hidden)
+    .map(([k, v]) => {
+      v.name = k
+      return v
+    }), f => [!f.char, f.char, f.name])
+    const args = (cmd.args || []).filter(a => !a.hidden)
+    let output = compact([
+      this.usage(flags),
+      this.args(args),
+      this.flags(flags),
+      this.description(),
+      this.aliases(cmd.aliases),
+      this.examples(cmd.examples || (cmd as any).example),
+    ]).join('\n\n')
+    if (this.opts.stripAnsi) output = stripAnsi(output)
+    return output
+  }
+
+  protected usage(flags: Config.Command.Flag[]): string {
+    const usage = this.command.usage
+    const body = (usage ? castArray(usage) : [this.defaultUsage(flags)])
+    .map(u => `$ ${this.config.bin} ${u}`.trim())
+    .join('\n')
+    return [
+      bold('USAGE'),
+      indent(wrap(this.render(body), this.opts.maxWidth - 2, {trim: false, hard: true}), 2),
+    ].join('\n')
+  }
+
+  protected defaultUsage(_: Config.Command.Flag[]): string {
+    return compact([
+      this.command.id,
+      this.command.args.filter(a => !a.hidden).map(a => this.arg(a)).join(' '),
+    ]).join(' ')
+  }
+
+  protected description(): string | undefined {
+    const cmd = this.command
+    const description = cmd.description && this.render(cmd.description).split('\n').slice(1).join('\n')
+    if (!description) return
+    return [
+      bold('DESCRIPTION'),
+      indent(wrap(description.trim(), this.opts.maxWidth - 2, {trim: false, hard: true}), 2),
+    ].join('\n')
+  }
+
+  protected aliases(aliases: string[] | undefined): string | undefined {
+    if (!aliases || aliases.length === 0) return
+    const body = aliases.map(a => ['$', this.config.bin, a].join(' ')).join('\n')
+    return [
+      bold('ALIASES'),
+      indent(wrap(body, this.opts.maxWidth - 2, {trim: false, hard: true}), 2),
+    ].join('\n')
+  }
+
+  protected examples(examples: string[] | undefined | string): string | undefined {
+    if (!examples || examples.length === 0) return
+    const body = castArray(examples).map(a => this.render(a)).join('\n')
+    return [
+      bold('EXAMPLE' + (examples.length > 1 ? 'S' : '')),
+      indent(wrap(body, this.opts.maxWidth - 2, {trim: false, hard: true}), 2),
+    ].join('\n')
+  }
+
+  protected args(args: Config.Command['args']): string | undefined {
+    if (args.filter(a => a.description).length === 0) return
+    const body = renderList(args.map(a => {
+      const name = a.name.toUpperCase()
+      let description = a.description || ''
+      // `a.default` is actually not always a string (typing bug), hence `toString()`
+      if (a.default || a.default?.toString() === '0') description = `[default: ${a.default}] ${description}`
+      if (a.options) description = `(${a.options.join('|')}) ${description}`
+      return [name, description ? dim(description) : undefined]
+    }), {stripAnsi: this.opts.stripAnsi, maxWidth: this.opts.maxWidth - 2})
+    return [
+      bold('ARGUMENTS'),
+      indent(body, 2),
+    ].join('\n')
+  }
+
+  protected arg(arg: Config.Command['args'][0]): string {
+    const name = arg.name.toUpperCase()
+    if (arg.required) return `${name}`
+    return `[${name}]`
+  }
+
+  protected flags(flags: Config.Command.Flag[]): string | undefined {
+    if (flags.length === 0) return
+    const body = renderList(flags.map(flag => {
+      let left = flag.helpLabel
+
+      if (!left) {
+        const label = []
+        if (flag.char) label.push(`-${flag.char[0]}`)
+        if (flag.name) {
+          if (flag.type === 'boolean' && flag.allowNo) {
+            label.push(`--[no-]${flag.name.trim()}`)
+          } else {
+            label.push(`--${flag.name.trim()}`)
+          }
+        }
+
+        left = label.join(', ')
+      }
+
+      if (flag.type === 'option') {
+        let value = flag.helpValue || flag.name
+        if (!flag.helpValue && flag.options) {
+          value = flag.options.join('|')
+        }
+
+        if (!value.includes('|')) value = underline(value)
+        left += `=${value}`
+      }
+
+      let right = flag.description || ''
+      // `flag.default` is not always a string (typing bug), hence `toString()`
+      if (flag.type === 'option' && (flag.default || flag.default?.toString() === '0')) {
+        right = `[default: ${flag.default}] ${right}`
+      }
+
+      if (flag.required) right = `(required) ${right}`
+
+      return [left, dim(right.trim())]
+    }), {stripAnsi: this.opts.stripAnsi, maxWidth: this.opts.maxWidth - 2})
+    return [
+      bold('OPTIONS'),
+      indent(body, 2),
+    ].join('\n')
+  }
+}

src/global.d.ts

@@ -0,0 +1,5 @@
+declare namespace NodeJS {
+  interface Global {
+    'columns': number;
+  }
+}