File Explorer

1const spawn = require('@npmcli/promise-spawn')2const path = require('node:path')3const { openUrl } = require('../utils/open-url.js')4const { glob } = require('glob')5const { output, input } = require('proc-log')6const localeCompare = require('@isaacs/string-locale-compare')('en')7const { deref } = require('../utils/cmd-list.js')8const BaseCommand = require('../base-cmd.js')9 10const globify = pattern => pattern.split('\\').join('/')11 12// Strips out the number from foo.7 or foo.7. or foo.7.tgz13// We don't currently compress our man pages but if we ever did this would14// seamlessly continue supporting it15const manNumberRegex = /\.(\d+)(\.[^/\\]*)?$/16// hardcoded names for man sections17// XXX: these are used in the docs workspace and should be exported18// from npm so section names can changed more easily19const manSectionNames = {20  1: 'commands',21  5: 'configuring-npm',22  7: 'using-npm',23}24 25class Help extends BaseCommand {26  static description = 'Get help on npm'27  static name = 'help'28  static usage = ['<term> [<terms..>]']29  static params = ['viewer']30 31  static async completion (opts, npm) {32    if (opts.conf.argv.remain.length > 2) {33      return []34    }35    const g = path.resolve(npm.npmRoot, 'man/man[0-9]/*.[0-9]')36    let files = await glob(globify(g))37    // preserve glob@8 behavior38    files = files.sort((a, b) => a.localeCompare(b, 'en'))39 40    return Object.keys(files.reduce(function (acc, file) {41      file = path.basename(file).replace(/\.[0-9]+$/, '')42      file = file.replace(/^npm-/, '')43      acc[file] = true44      return acc45    }, { help: true }))46  }47 48  async exec (args) {49    // By default we search all of our man subdirectories, but if the user has50    // asked for a specific one we limit the search to just there51    const manSearch = /^\d+$/.test(args[0]) ? `man${args.shift()}` : 'man*'52 53    if (!args.length) {54      return output.standard(this.npm.usage)55    }56 57    // npm help foo bar baz: search topics58    if (args.length > 1) {59      return this.helpSearch(args)60    }61 62    // `npm help package.json`63    const arg = (deref(args[0]) || args[0]).replace('.json', '-json')64 65    // find either section.n or npm-section.n66    const f = globify(path.resolve(this.npm.npmRoot, `man/${manSearch}/?(npm-)${arg}.[0-9]*`))67 68    const [man] = await glob(f).then(r => r.sort((a, b) => {69      // Because the glob is (subtly) different from manNumberRegex,70      // we can't rely on it passing.71      const aManNumberMatch = a.match(manNumberRegex)?.[1] || 99972      const bManNumberMatch = b.match(manNumberRegex)?.[1] || 99973      if (aManNumberMatch !== bManNumberMatch) {74        return aManNumberMatch - bManNumberMatch75      }76      return localeCompare(a, b)77    }))78 79    return man ? this.viewMan(man) : this.helpSearch(args)80  }81 82  helpSearch (args) {83    return this.npm.exec('help-search', args)84  }85 86  async viewMan (man) {87    const viewer = this.npm.config.get('viewer')88 89    if (viewer === 'browser') {90      return openUrl(this.npm, this.htmlMan(man), 'help available at the following URL', true)91    }92 93    let args = ['man', [man]]94    if (viewer === 'woman') {95      args = ['emacsclient', ['-e', `(woman-find-file '${man}')`]]96    }97 98    try {99      await input.start(() => spawn(...args, { stdio: 'inherit' }))100    } catch (err) {101      if (err.code) {102        throw new Error(`help process exited with code: ${err.code}`)103      } else {104        throw err105      }106    }107  }108 109  // Returns the path to the html version of the man page110  htmlMan (man) {111    const sect = manSectionNames[man.match(manNumberRegex)[1]]112    const f = path.basename(man).replace(manNumberRegex, '')113    return 'file:///' + path.resolve(this.npm.npmRoot, `docs/output/${sect}/${f}.html`)114  }115}116 117module.exports = Help118