{"id":13464934,"url":"https://github.com/hapipal/hpal","last_synced_at":"2025-05-05T17:54:41.295Z","repository":{"id":45576748,"uuid":"102410190","full_name":"hapipal/hpal","owner":"hapipal","description":"hapi pal CLI","archived":false,"fork":false,"pushed_at":"2023-02-24T01:28:45.000Z","size":406,"stargazers_count":51,"open_issues_count":8,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-26T12:39:32.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hapipal.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hapipal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-09-04T23:13:16.000Z","updated_at":"2024-01-10T20:29:12.000Z","dependencies_parsed_at":"2024-01-16T05:41:37.462Z","dependency_job_id":"50269189-b010-4a1d-8e69-2ce718f09084","html_url":"https://github.com/hapipal/hpal","commit_stats":{"total_commits":181,"total_committers":11,"mean_commits":"16.454545454545453","dds":"0.22099447513812154","last_synced_commit":"4661f17ac8bdb1d3915695b2f819ff2336730131"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fhpal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fhpal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fhpal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hapipal%2Fhpal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hapipal","download_url":"https://codeload.github.com/hapipal/hpal/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252546454,"owners_count":21765772,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T14:00:53.045Z","updated_at":"2025-05-05T17:54:41.272Z","avatar_url":"https://github.com/hapipal.png","language":"JavaScript","readme":"# hpal\n\nhapi pal CLI\n\n[![Build Status](https://travis-ci.com/hapipal/hpal.svg?branch=master)](https://travis-ci.com/hapipal/hpal) [![Coverage Status](https://coveralls.io/repos/hapipal/hpal/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/hapipal/hpal?branch=master)\n\nLead Maintainer - [Devin Ivy](https://github.com/devinivy)\n\n`hpal` was designed to help you,\n  - :sparkles: create new hapi projects from the [pal boilerplate](https://github.com/hapipal/boilerplate)\n  - :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)\n  - :books: search the [hapi docs](https://hapi.dev/api/) from the command line– plus many others such as [joi](https://joi.dev/api/) and [toys](https://hapipal.com/docs/toys)\n  - :honeybee: run custom commands defined by your server's hapi plugins\n\n## Installation\n\nIt is recommended to install the hpal CLI as a dev dependency within your project, then invoke it using [npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b).\n\n```\nnpm install --save-dev @hapipal/hpal\nnpx hpal --help\n```\n\nHowever, if you want to try the hpal CLI right now, just copy and paste this right into your terminal!\n```\nnpx @hapipal/hpal docs --ver 20.0.0 h.response\n```\n\n## Usage\n\u003e The hpal CLI is intended for use with hapi v19+ and nodejs v12+ (_see v2 for lower support_).\n\n```\nUsage: hpal \u003ccommand\u003e \u003coptions\u003e\n\nCommands:\n\n  hpal new \u003cnew-project-directory\u003e\n    e.g. hpal new ~/node-projects/new-pal-project\n\n  hpal make [--asDir|--asFile] \u003chaute-couture-item\u003e [\u003citem-name\u003e]\n    e.g. hpal make route create-user\n\n  hpal docs[:\u003cpackage-name\u003e] [--ver x.y.z|ref] \u003cdocs-section\u003e [\u003cconfig-item\u003e]\n    e.g. hpal docs --ver 20.0.0 h.continue\n\n  hpal run [--list] \u003ccmd\u003e [\u003ccmd-options\u003e]\n    e.g. hpal run plugin-name:command-name\n\n\nOptions:\n\n  -h, --help       show usage options\n  -v, --version    show version information\n  -d, --asDir      [make] creates new haute-couture item in a directory index file\n  -f, --asFile     [make] creates new haute-couture item in a file\n  -V, --ver        [docs] specifies the version/ref of the API docs to search for the given package\n  -l, --list       [run] lists all available commands on your server\n```\n\n### Commands\n#### `hpal new`\n\u003e ```\n\u003e hpal new \u003cnew-project-directory\u003e\n\u003e   e.g. hpal new ~/node-projects/new-pal-project\n\u003e ```\n\nClones 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.\n\n#### `hpal make`\n\u003e ```\n\u003e hpal make [--asDir|--asFile] \u003chaute-couture-item\u003e [\u003citem-name\u003e]\n\u003e   e.g. hpal make route create-user\n\u003e ```\n\nCreates a new file for a [haute-couture item](https://hapipal.com/docs/haute-couture#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.\n\nRelies on the presence of a [`.hc.js`](https://hapipal.com/docs/haute-couture#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`.\n\nThe `--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 `\u003citem-name\u003e` is specified then that will always place a file in the relevant directory with the name `\u003citem-name\u003e.js`.  For example, `hpal make route create-user` will write the file `routes/create-user.js`.\n\nIn 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 amendment.\n\n#### `hpal docs`\n\u003e ```\n\u003e hpal docs[:\u003cpackage-name\u003e] [--ver x.y.z|ref] \u003cdocs-section\u003e [\u003cconfig-item\u003e]\n\u003e   e.g. hpal docs --ver 20.0.0 h.continue\n\u003e ```\n\nSearches the [hapi API reference](https://hapi.dev/api/) for the relevant section or configuration item then prints it formatted to the console.\n\n:dizzy: This command can also search the API reference for any package within the pal and hapijs ecosystems by specifying `\u003cpackage-name\u003e`, e.g. [`hpal docs:toys noop`](https://hapipal.com/docs/toys#toysnoop) or [`hpal docs:joi any.strip`](https://joi.dev/api/#anystrip).\n\n`\u003cdocs-section\u003e` can be,\n - the name of any haute-couture item (e.g. `route`, `plugins`, `auth/default`) when in a haute-couture project\n   - e.g. [`hpal docs auth/scheme`](https://hapi.dev/api/#server.auth.scheme())\n - the name of any server, request, toolkit, etc. method\n   - e.g. [`hpal docs request.setUrl`](https://hapi.dev/api/#request.setUrl())\n - a substring of any heading from the docs\n   - e.g. [`hpal docs router`](https://hapi.dev/api/#server.options.router)\n - an anchor seen anywhere in the docs\n   - e.g. [`hpal docs '#catch-all-route'`](https://hapi.dev/api/#catch-all-route)\n\nWhen `\u003cconfig-item\u003e` is also specified, the first list item within the matched `\u003cdocs-section\u003e` that matches text from `\u003cconfig-item\u003e` 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.\n\nAll searches are case-insensitive.\n\nWhen `--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.\n\n#### `hpal run`\n\u003e ```\n\u003e hpal run [--list] \u003ccmd\u003e [\u003ccmd-options\u003e]\n\u003e   e.g. hpal run plugin-name:command-name\n\u003e ```\n\nRuns the command `\u003ccmd\u003e` 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`.\n\nA list of commands available on the server and their descriptions may be viewed with `hpal run --list`.\n\nUpon running a command hpal will initialize the server if it is not already initialized, then stop the server when the command exits successfully.\n\n##### Requirements\n\nIn 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).\n\nIf you're using the [pal boilerplate](https://github.com/hapipal/boilerplate) then you should already be all set!\n\nHere is a very basic example,\n```js\n// server/index.js\nconst Hapi = require('hapi');\nconst AppPlugin = require('../app');\n\nexports.deployment = async ({ start } = {}) =\u003e {\n\n    const server = Hapi.server();\n\n    await server.register(AppPlugin);\n\n    if (start) {\n        await server.start();\n    }\n\n    return server;\n};\n\n// Start the server only when this file is\n// run directly from the CLI, i.e. \"node ./server\"\n\nif (!module.parent) {\n    exports.deployment({ start: true });\n}\n```\n\n##### Creating your own commands\n\nAny hapi plugin can create commands that are runnable with `hpal run`!  Commands are exposed to hpal using hapi's [`server.expose()`](https://hapi.dev/api/#server.expose()).  Inside your plugin `my-plugin` simply call `server.expose('commands', commands)`, where `commands` is an object,\n - 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`.\n - whose values are either objects `{ command, description }` or functions `command` where,\n   - `command` - a function with the signature `async function(server, args, root, ctx)`.\n     - `server` - the initialized hapi server.\n     - `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']`.\n     - `root` - an absolute path to the project's root directory.\n     - `ctx` - a context object containing some hpal internals that may be useful during testing, plus some public helpers.  The following are public:\n       - `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.\n       - `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.\n   - `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.\n\nFor example, here is a plugin that creates a command to display the server's route table,\n```js\n// hpal run route-table:show\n\nmodule.exports = {\n    name: 'hpal-route-table', // The hpal- prefix is ignored when running the command\n    register(server) {\n\n        server.expose('commands', {\n            show(srv) {\n\n                console.log('Route table:');\n\n                srv.table().forEach(({ method, path }) =\u003e {\n\n                    console.log(`  ${method} ${path}`);\n                });\n            }\n        });\n    }\n};\n```\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapipal%2Fhpal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhapipal%2Fhpal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhapipal%2Fhpal/lists"}