first commit

node_modules/help-me/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        node-version: [14.x, 16.x, 18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Use Node.js
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install
+        run: |
+          npm install
+
+      - name: Run tests
+        run: |
+          npm run test

node_modules/help-me/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014-2022 Matteo Collina
+
+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.
+

node_modules/help-me/README.md

@@ -0,0 +1,66 @@
+help-me
+=======
+
+Help command for node, to use with [minimist](http://npm.im/minimist) and [commist](http://npm.im/commist).
+
+Example
+-------
+
+```js
+'use strict'
+
+var helpMe = require('help-me')
+var path = require('path')
+var help = helpMe({
+  dir: path.join(__dirname, 'doc'),
+  // the default
+  ext: '.txt'
+})
+
+help
+  .createStream(['hello']) // can support also strings
+  .pipe(process.stdout)
+
+// little helper to do the same
+help.toStdout(['hello'])
+```
+
+Using ESM and top-level await::
+
+```js
+import { help } from 'help-me'
+import { join } from 'desm'
+
+await help({
+  dir: join(import.meta.url, 'doc'),
+  // the default
+  ext: '.txt'
+}, ['hello'])
+```
+
+Usage with commist
+------------------
+
+[Commist](http://npm.im/commist) provide a command system for node.
+
+```js
+var commist = require('commist')()
+var path = require('path')
+var help = require('help-me')({
+  dir: path.join(__dirname, 'doc')
+})
+
+commist.register('help', help.toStdout)
+
+commist.parse(process.argv.splice(2))
+```
+
+Acknowledgements
+----------------
+
+This project was kindly sponsored by [nearForm](http://nearform.com).
+
+License
+-------
+
+MIT

node_modules/help-me/doc/hello.txt

@@ -0,0 +1 @@
+this is hello world

node_modules/help-me/doc/help.txt

@@ -0,0 +1,5 @@
+HELP-ME by Matteo
+
+* start     starts a script
+* help      shows help
+

node_modules/help-me/example.js

@@ -0,0 +1,18 @@
+'use strict'
+
+const path = require('path')
+const commist = require('commist')()
+const help = require('./')({
+  dir: path.join(path.dirname(require.main.filename), 'doc')
+})
+
+commist.register('help', help.toStdout)
+commist.register('start', function () {
+  console.log('Starting the script!')
+})
+
+const res = commist.parse(process.argv.splice(2))
+
+if (res) {
+  help.toStdout()
+}

node_modules/help-me/fixture/basic/hello.txt

@@ -0,0 +1 @@
+ahdsadhdash

node_modules/help-me/fixture/basic/help.txt

@@ -0,0 +1 @@
+hello world

node_modules/help-me/fixture/no-ext/hello

@@ -0,0 +1 @@
+ghghghhg

node_modules/help-me/fixture/sameprefix/hello world.txt

@@ -0,0 +1 @@
+hello world

node_modules/help-me/fixture/sameprefix/hello.txt

@@ -0,0 +1 @@
+hello

node_modules/help-me/fixture/shortnames/abcde fghi lmno.txt

@@ -0,0 +1 @@
+ewweqjewqjewqj

node_modules/help-me/fixture/shortnames/abcde hello.txt

@@ -0,0 +1 @@
+45678

node_modules/help-me/fixture/shortnames/hello world.txt

@@ -0,0 +1 @@
+12345

node_modules/help-me/help-me.js

@@ -0,0 +1,134 @@
+'use strict'
+
+const fs = require('fs')
+const { PassThrough, Writable, pipeline } = require('stream')
+const process = require('process')
+const { join } = require('path')
+
+const defaults = {
+  ext: '.txt',
+  help: 'help'
+}
+
+function isDirectory (path) {
+  try {
+    const stat = fs.lstatSync(path)
+    return stat.isDirectory()
+  } catch (err) {
+    return false
+  }
+}
+
+function createDefaultStream () {
+  return new Writable({
+    write (chunk, encoding, callback) {
+      process.stdout.write(chunk, callback)
+    }
+  })
+}
+
+function helpMe (opts) {
+  opts = Object.assign({}, defaults, opts)
+
+  if (!opts.dir) {
+    throw new Error('missing dir')
+  }
+
+  if (!isDirectory(opts.dir)) {
+    throw new Error(`${opts.dir} is not a directory`)
+  }
+
+  return {
+    createStream: createStream,
+    toStdout: toStdout
+  }
+
+  function createStream (args) {
+    if (typeof args === 'string') {
+      args = args.split(' ')
+    } else if (!args || args.length === 0) {
+      args = [opts.help]
+    }
+
+    const out = new PassThrough()
+    const re = new RegExp(
+      args
+        .map(function (arg) {
+          return arg + '[a-zA-Z0-9]*'
+        })
+        .join('[ /]+')
+    )
+
+    if (process.platform === 'win32') {
+      opts.dir = opts.dir.split('\\').join('/')
+    }
+
+    fs.readdir(opts.dir, function (err, files) {
+      if (err) return out.emit('error', err)
+
+      const regexp = new RegExp('.*' + opts.ext + '$')
+      files = files
+        .filter(function (file) {
+          const matched = file.match(regexp)
+          return !!matched
+        })
+        .map(function (relative) {
+          return { file: join(opts.dir, relative), relative }
+        })
+        .filter(function (file) {
+          return file.relative.match(re)
+        })
+
+      if (files.length === 0) {
+        return out.emit('error', new Error('no such help file'))
+      } else if (files.length > 1) {
+        const exactMatch = files.find(
+          (file) => file.relative === `${args[0]}${opts.ext}`
+        )
+        if (!exactMatch) {
+          out.write('There are ' + files.length + ' help pages ')
+          out.write('that matches the given request, please disambiguate:\n')
+          files.forEach(function (file) {
+            out.write('  * ')
+            out.write(file.relative.replace(opts.ext, ''))
+            out.write('\n')
+          })
+          out.end()
+          return
+        }
+        files = [exactMatch]
+      }
+
+      pipeline(fs.createReadStream(files[0].file), out, () => {})
+    })
+
+    return out
+  }
+
+  function toStdout (args = [], opts) {
+    opts = opts || {}
+    const stream = opts.stream || createDefaultStream()
+    const _onMissingHelp = opts.onMissingHelp || onMissingHelp
+    return new Promise((resolve, reject) => {
+      createStream(args)
+        .on('error', (err) => {
+          _onMissingHelp(err, args, stream).then(resolve, reject)
+        })
+        .pipe(stream)
+        .on('close', resolve)
+        .on('end', resolve)
+    })
+  }
+
+  function onMissingHelp (_, args, stream) {
+    stream.write(`no such help file: ${args.join(' ')}.\n\n`)
+    return toStdout([], { stream, async onMissingHelp () {} })
+  }
+}
+
+function help (opts, args) {
+  return helpMe(opts).toStdout(args, opts)
+}
+
+module.exports = helpMe
+module.exports.help = help

node_modules/help-me/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "help-me",
+  "version": "5.0.0",
+  "description": "Help command for node, partner of minimist and commist",
+  "main": "help-me.js",
+  "scripts": {
+    "test": "standard && node test.js | tap-spec"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcollina/help-me.git"
+  },
+  "keywords": [
+    "help",
+    "command",
+    "minimist",
+    "commist"
+  ],
+  "author": "Matteo Collina <hello@matteocollina.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mcollina/help-me/issues"
+  },
+  "homepage": "https://github.com/mcollina/help-me",
+  "devDependencies": {
+    "commist": "^2.0.0",
+    "concat-stream": "^2.0.0",
+    "pre-commit": "^1.1.3",
+    "proxyquire": "^2.1.3",
+    "standard": "^16.0.0",
+    "tap-spec": "^5.0.0",
+    "tape": "^5.0.0"
+  },
+  "dependencies": {
+  }
+}

node_modules/help-me/test.js

@@ -0,0 +1,316 @@
+'use strict'
+
+const test = require('tape')
+const concat = require('concat-stream')
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const helpMe = require('./')
+const proxyquire = require('proxyquire')
+
+test('throws if no directory is passed', function (t) {
+  try {
+    helpMe()
+    t.fail()
+  } catch (err) {
+    t.equal(err.message, 'missing dir')
+  }
+  t.end()
+})
+
+test('throws if a normal file is passed', function (t) {
+  try {
+    helpMe({
+      dir: __filename
+    })
+    t.fail()
+  } catch (err) {
+    t.equal(err.message, `${__filename} is not a directory`)
+  }
+  t.end()
+})
+
+test('throws if the directory cannot be accessed', function (t) {
+  try {
+    helpMe({
+      dir: './foo'
+    })
+    t.fail()
+  } catch (err) {
+    t.equal(err.message, './foo is not a directory')
+  }
+  t.end()
+})
+
+test('show a generic help.txt from a folder to a stream with relative path in dir', function (t) {
+  t.plan(2)
+
+  helpMe({
+    dir: 'fixture/basic'
+  }).createStream()
+    .pipe(concat(function (data) {
+      fs.readFile('fixture/basic/help.txt', function (err, expected) {
+        t.error(err)
+        t.equal(data.toString(), expected.toString())
+      })
+    }))
+})
+
+test('show a generic help.txt from a folder to a stream with absolute path in dir', function (t) {
+  t.plan(2)
+
+  helpMe({
+    dir: path.join(__dirname, 'fixture/basic')
+  }).createStream()
+    .pipe(concat(function (data) {
+      fs.readFile('fixture/basic/help.txt', function (err, expected) {
+        t.error(err)
+        t.equal(data.toString(), expected.toString())
+      })
+    }))
+})
+
+test('custom help command with an array', function (t) {
+  t.plan(2)
+
+  helpMe({
+    dir: 'fixture/basic'
+  }).createStream(['hello'])
+    .pipe(concat(function (data) {
+      fs.readFile('fixture/basic/hello.txt', function (err, expected) {
+        t.error(err)
+        t.equal(data.toString(), expected.toString())
+      })
+    }))
+})
+
+test('custom help command without an ext', function (t) {
+  t.plan(2)
+
+  helpMe({
+    dir: 'fixture/no-ext',
+    ext: ''
+  }).createStream(['hello'])
+    .pipe(concat(function (data) {
+      fs.readFile('fixture/no-ext/hello', function (err, expected) {
+        t.error(err)
+        t.equal(data.toString(), expected.toString())
+      })
+    }))
+})
+
+test('custom help command with a string', function (t) {
+  t.plan(2)
+
+  helpMe({
+    dir: 'fixture/basic'
+  }).createStream('hello')
+    .pipe(concat(function (data) {
+      fs.readFile('fixture/basic/hello.txt', function (err, expected) {
+        t.error(err)
+        t.equal(data.toString(), expected.toString())
+      })
+    }))
+})
+
+test('missing help file', function (t) {
+  t.plan(1)
+
+  helpMe({
+    dir: 'fixture/basic'
+  }).createStream('abcde')
+    .on('error', function (err) {
+      t.equal(err.message, 'no such help file')
+    })
+    .resume()
+})
+
+test('custom help command with an array', function (t) {
+  const helper = helpMe({
+    dir: 'fixture/shortnames'
+  })
+
+  t.test('abbreviates two words in one', function (t) {
+    t.plan(2)
+
+    helper
+      .createStream(['world'])
+      .pipe(concat(function (data) {
+        fs.readFile('fixture/shortnames/hello world.txt', function (err, expected) {
+          t.error(err)
+          t.equal(data.toString(), expected.toString())
+        })
+      }))
+  })
+
+  t.test('abbreviates three words in two', function (t) {
+    t.plan(2)
+
+    helper
+      .createStream(['abcde', 'fghi'])
+      .pipe(concat(function (data) {
+        fs.readFile('fixture/shortnames/abcde fghi lmno.txt', function (err, expected) {
+          t.error(err)
+          t.equal(data.toString(), expected.toString())
+        })
+      }))
+  })
+
+  t.test('abbreviates a word', function (t) {
+    t.plan(2)
+
+    helper
+      .createStream(['abc', 'fg'])
+      .pipe(concat(function (data) {
+        fs.readFile('fixture/shortnames/abcde fghi lmno.txt', function (err, expected) {
+          t.error(err)
+          t.equal(data.toString(), expected.toString())
+        })
+      }))
+  })
+
+  t.test('abbreviates a word using strings', function (t) {
+    t.plan(2)
+
+    helper
+      .createStream('abc fg')
+      .pipe(concat(function (data) {
+        fs.readFile('fixture/shortnames/abcde fghi lmno.txt', function (err, expected) {
+          t.error(err)
+          t.equal(data.toString(), expected.toString())
+        })
+      }))
+  })
+
+  t.test('print a disambiguation', function (t) {
+    t.plan(1)
+
+    const expected = '' +
+      'There are 2 help pages that matches the given request, please disambiguate:\n' +
+      '  * abcde fghi lmno\n' +
+      '  * abcde hello\n'
+
+    helper
+      .createStream(['abc'])
+      .pipe(concat({ encoding: 'string' }, function (data) {
+        t.equal(data, expected)
+      }))
+  })
+
+  t.test('choose exact match over partial', function (t) {
+    t.plan(1)
+
+    helpMe({
+      dir: 'fixture/sameprefix'
+    }).createStream(['hello'])
+      .pipe(concat({ encoding: 'string' }, function (data) {
+        t.equal(data, 'hello')
+      }))
+  })
+})
+
+test('toStdout helper', async function (t) {
+  t.plan(2)
+
+  let completed = false
+  const stream = concat(function (data) {
+    completed = true
+    fs.readFile('fixture/basic/help.txt', function (err, expected) {
+      t.error(err)
+      t.equal(data.toString(), expected.toString())
+    })
+  })
+
+  await helpMe({
+    dir: 'fixture/basic'
+  }).toStdout([], { stream })
+
+  t.ok(completed)
+})
+
+test('handle error in toStdout', async function (t) {
+  t.plan(2)
+
+  let completed = false
+  const stream = concat(function (data) {
+    completed = true
+    fs.readFile('fixture/basic/help.txt', function (err, expected) {
+      t.error(err)
+      t.equal(data.toString(), 'no such help file: something.\n\n' + expected.toString())
+    })
+  })
+
+  await helpMe({
+    dir: 'fixture/basic'
+  }).toStdout(['something'], {
+    stream
+  })
+
+  t.ok(completed)
+})
+
+test('customize missing help fle message', async function (t) {
+  t.plan(3)
+
+  const stream = concat(function (data) {
+    t.equal(data.toString(), 'kaboom\n\n')
+  })
+
+  await helpMe({
+    dir: 'fixture/basic'
+  }).toStdout(['something'], {
+    stream,
+    async onMissingHelp (err, args, stream) {
+      t.equal(err.message, 'no such help file')
+      t.deepEquals(args, ['something'])
+      stream.end('kaboom\n\n')
+    }
+  })
+})
+
+test('toStdout without factory', async function (t) {
+  t.plan(2)
+
+  let completed = false
+  const stream = concat(function (data) {
+    completed = true
+    fs.readFile('fixture/basic/help.txt', function (err, expected) {
+      t.error(err)
+      t.equal(data.toString(), expected.toString())
+    })
+  })
+
+  await helpMe.help({
+    dir: 'fixture/basic',
+    stream
+  }, [])
+
+  t.ok(completed)
+})
+
+test('should allow for awaiting the response with default stdout stream', async function (t) {
+  t.plan(2)
+
+  const _process = Object.create(process)
+  const stdout = Object.create(process.stdout)
+  Object.defineProperty(_process, 'stdout', {
+    value: stdout
+  })
+
+  let completed = false
+  stdout.write = (data, cb) => {
+    t.equal(data.toString(), 'hello world' + os.EOL)
+    completed = true
+    cb()
+  }
+
+  const helpMe = proxyquire('./help-me', {
+    process: _process
+  })
+
+  await helpMe.help({
+    dir: 'fixture/basic'
+  })
+
+  t.ok(completed)
+})