# hpal hapi pal CLI [![Build Status](https://travis-ci.org/hapipal/hpal.svg?branch=master)](https://travis-ci.org/hapipal/hpal) [![Coverage Status](https://coveralls.io/repos/hapipal/hpal/badge.svg?branch=master&service=github)](https://coveralls.io/github/hapipal/hpal?branch=master) Lead Maintainer - [Devin Ivy](https://github.com/devinivy) `hpal` was designed to help you, - :sparkles: create new hapi projects from the [pal boilerplate](https://github.com/hapipal/boilerplate) - :bouquet: generate files for routes, extensions, [models](https://github.com/hapipal/schwifty), [services](https://github.com/hapipal/schmervice), etc. via [`haute-couture`](https://github.com/hapipal/haute-couture) - :books: search the [hapi docs](https://github.com/hapijs/hapi/blob/master/API.md) from the command line– plus many others such as [joi](https://github.com/hapijs/joi/blob/master/API.md) and [toys](https://github.com/hapipal/toys/blob/master/API.md) - :honeybee: run custom commands defined by your server's hapi plugins ## Installation > Note, the hpal CLI is designed for use with **hapi v17+** and **nodejs v8+**. We recommend installing the hpal CLI as a dev dependency within your project, then invoking it using [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b). ``` npm install --save-dev hpal npx hpal --help ``` If you want to try the hpal CLI right now, just copy and paste this right into your terminal! ``` npx hpal docs --ver 18.1.0 h.response ``` ## Usage ``` Usage: hpal Commands: hpal new e.g. hpal new ~/node-projects/new-pal-project hpal make [--asDir|--asFile] [] e.g. hpal make route create-user hpal docs[:] [--ver x.y.z|ref] [] e.g. hpal docs --ver 17.2.0 h.continue hpal run [--list] [] e.g. hpal run plugin-name:command-name Options: -h, --help show usage options -v, --version show version information -d, --asDir [make] creates new haute-couture item in a directory index file -f, --asFile [make] creates new haute-couture item in a file -V, --ver [docs] specifies the version/ref of the API docs to search for the given package -l, --list [run] lists all available commands on your server ``` ### Commands #### `hpal new` > ``` > hpal new > e.g. hpal new ~/node-projects/new-pal-project > ``` Clones the [pal boilerplate](https://github.com/hapipal/boilerplate), helps you fill-in initial details with [`npm init`](https://docs.npmjs.com/cli/init), pulls down the [pal flavors](https://github.com/hapipal/boilerplate#flavors), and leaves you prepared to make the first commit to your new project. #### `hpal make` > ``` > hpal make [--asDir|--asFile] [] > e.g. hpal make route create-user > ``` Creates a new file for a [`haute-couture` item](https://github.com/hapipal/haute-couture/blob/master/API.md#files-and-directories) with details ready to be filled-in. This is the best way to add a route, plugin, model, service, etc. to any project that uses haute-couture. Relies on the presence of a [`.hc.js`](https://github.com/hapipal/haute-couture/blob/master/API.md#specifying-amendments-with-hcjs) file in the project, even if it's empty, in order to determine the base directory of the plugin in which to write the file. If `.hc.js` contains amendments then those will be respected– in this way you can customize the behavior of `hpal make` per project. Projects created with [`hpal new`](#hpal-new) are already configured to work with `hpal make`. The `--asDir` and `--asFile` flags can be used to determine where the file is written. For a list item like `routes`, specifying `--asFile` (`hpal make route --asFile`) will create `routes.js` rather than `routes/index.js`. For a single item like `auth/default`, specifying `--asDir` (`hpal make auth/default --asDir`) will create `auth/default/index.js` rather than `auth/default.js`. When an optional `` is specified then that will always place a file in the relevant directory with the name `.js`. For example, `hpal make route create-user` will write the file `routes/create-user.js`. In order to omit the statement to enable [strict mode](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Strict_mode) to the top of the generated files (per the hapi style guide), you may specify `exampleUseStrict` as `false` inside the `meta` property of the relevant haute-couture manifest items. #### `hpal docs` > ``` > hpal docs[:] [--ver x.y.z|ref] [] > e.g. hpal docs --ver 17.2.0 h.continue > ``` Searches the [hapi API reference](https://github.com/hapijs/hapi/blob/master/API.md) for the relevant section or configuration item then prints it formatted to the console. :dizzy: This command can also search the API reference for any package within the pal and hapijs ecosystems by specifying ``, e.g. [`hpal docs:toys noop`](https://github.com/hapipal/toys/blob/master/API.md#toysnoop) or [`hpal docs:joi any.strip`](https://github.com/hapijs/joi/blob/master/API.md#anystrip). `` can be, - the name of any haute-couture item (e.g. `route`, `plugins`, `auth/default`) when in a haute-couture project - e.g. [`hpal docs auth/scheme`](https://github.com/hapijs/hapi/blob/master/API.md#server.auth.scheme()) - the name of any server, request, toolkit, etc. method - e.g. [`hpal docs request.setUrl`](https://github.com/hapijs/hapi/blob/master/API.md#request.setUrl()) - a substring of any heading from the docs - e.g. [`hpal docs router`](https://github.com/hapijs/hapi/blob/master/API.md#server.options.router) - an anchor seen anywhere in the docs - e.g. [`hpal docs '#catch-all-route'`](https://github.com/hapijs/hapi/blob/master/API.md#catch-all-route) When `` is also specified, the first list item within the matched `` that matches text from `` will be displayed on its own. For example, `hpal docs request.setUrl` is a long section of the docs but `hpal docs request.setUrl stripTrailingSlash` contains only information relevant to the `stripTrailingSlash` argument. All searches are case-insensitive. When `--ver` is specified as a semver version or a git ref (branch, tag, or commit), then that version of the docs will be searched. Otherwise, when inside a project the docs for the currently installed version of the given package will be searched. When not in a project and `--ver` is not specified, the master branch of the package's docs will be searched. #### `hpal run` > ``` > hpal run [--list] [] > e.g. hpal run plugin-name:command-name > ``` Runs the command `` defined by some plugin on your hapi server. If the plugin `my-plugin` defines a command `do-the-thing`, then that command can be run with `hpal run my-plugin:do-the-thing`. If the plugin's name is prefixed with `hpal-`, then `hpal-` may be omitted when running the command. Plugins may also have a "default" command that can be run as `hpal run my-plugin`. A list of commands available on the server and their descriptions may be viewed with `hpal run --list`. Upon running a command hpal will initialize the server if it is not already initialized, then stop the server when the command exits successfully. ##### Requirements In order to use `hpal run`, hpal must be able to find your hapi server. It will look in `server.js` and `server/index.js` relative to the root of your project. That file should export a property `deployment` which contains a function that returns a hapi server, or a promise for a hapi server (for example, an `async` function). If you're using the [pal boilerplate](https://github.com/hapipal/boilerplate) then you should already be all set! Here is a very basic example, ```js // server/index.js const Hapi = require('hapi'); const AppPlugin = require('../app'); exports.deployment = async (start) => { const server = Hapi.server(); await server.register(AppPlugin); if (start) { await server.start(); } return server; }; // Start the server only when this file is // run directly from the CLI, i.e. "node ./server" if (!module.parent) { exports.deployment(true); } ``` ##### Creating your own commands Any hapi plugin can create commands that are runnable with `hpal run`! Commands are exposed to hpal using hapi's [`server.expose()`](https://github.com/hapijs/hapi/blob/master/API.md#server.expose()). Inside your plugin `my-plugin` simply call `server.expose('commands', commands)`, where `commands` is an object, - whose keys are command names. The name `default` is reserved for the command `hpal run my-plugin`. Camel-cased command names are converted to kebab-case, so if the key is `someCommand` then it is run using `hpal run my-plugin:some-command`. - whose values are either objects `{ command, description }` or functions `command` where, - `command` - a function with the signature `async function(server, args, root, ctx)`. - `server` - the initialized hapi server. - `args` - an array of all the command's CLI arguments. For example, running `hpal run my-plugin --custom-flag value` will result in `args` being `['--custom-flag', 'value']`. - `root` - an absolute path to the project's root directory. - `ctx` - a context object containing some hpal internals that may be useful during testing, plus some public helpers. The following are public: - `colors` - an object with functions for basic formatting of CLI output with colors and styles: `colors.green(str)`, `colors.yellow(str)`, `colors.red(str)`, `colors.grey(str)`, and `colors.bold(str)`. When the CLI does not support color, these functions take no effect. - `DisplayError` - a class that can be used to indicate a "safe" failure to hpal. Throwing a `DisplayError` will output the error's `message` and exit the process with code `1`, but not display a stack trace as would happen with an unexpected error. - `description` - a string description of the command displayed by `hpal run --list`. May alternatively be a function with signature `function (ctx)` that receives `ctx` as described above and returns a string description. For example, here is a plugin that creates a command to display the server's route table, ```js // hpal run route-table:show module.exports = { name: 'hpal-route-table', // The hpal- prefix is ignored when running the command register(server) { server.expose('commands', { show(srv) { console.log('Route table:'); srv.table().forEach(({ method, path }) => { console.log(` ${method} ${path}`); }); } }); } }; ```