@farthershore/cli 0.3.9 → 0.3.10

package/node_modules/pino/docs/help.md

@@ -0,0 +1,345 @@
+# Help
+
+* [Log rotation](#rotate)
+* [Reopening log files](#reopening)
+* [Saving to multiple files](#multiple)
+* [Log filtering](#filter-logs)
+* [Transports and systemd](#transport-systemd)
+* [Log to different streams](#multi-stream)
+* [Duplicate keys](#dupe-keys)
+* [Log levels as labels instead of numbers](#level-string)
+* [Pino with `debug`](#debug)
+* [Unicode and Windows terminal](#windows)
+* [Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Severity Levels](#stackdriver)
+* [Using Grafana Loki to evaluate pino logs in a kubernetes cluster](#grafana-loki)
+* [Avoid Message Conflict](#avoid-message-conflict)
+* [Best performance for logging to `stdout`](#best-performance-for-stdout)
+* [Testing](#testing)
+
+<a id="rotate"></a>
+## Log rotation
+
+Use a separate tool for log rotation:
+We recommend [logrotate](https://github.com/logrotate/logrotate).
+Consider we output our logs to `/var/log/myapp.log` like so:
+
+```
+$ node server.js > /var/log/myapp.log
+```
+
+We would rotate our log files with logrotate, by adding the following to `/etc/logrotate.d/myapp`:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       copytruncate
+}
+```
+
+The `copytruncate` configuration has a very slight possibility of lost log lines due
+to a gap between copying and truncating - the truncate may occur after additional lines
+have been written. To perform log rotation without `copytruncate`, see the [Reopening log files](#reopening)
+help.
+
+<a id="reopening"></a>
+## Reopening log files
+
+In cases where a log rotation tool doesn't offer copy-truncate capabilities,
+or where using them is deemed inappropriate, `pino.destination`
+can reopen file paths after a file has been moved away.
+
+One way to use this is to set up a `SIGUSR2` or `SIGHUP` signal handler that
+reopens the log file destination, making sure to write the process PID out
+somewhere so the log rotation tool knows where to send the signal.
+
+```js
+// write the process pid to a well known location for later
+const fs = require('node:fs')
+fs.writeFileSync('/var/run/myapp.pid', process.pid)
+
+const dest = pino.destination('/log/file')
+const logger = require('pino')(dest)
+process.on('SIGHUP', () => dest.reopen())
+```
+
+The log rotation tool can then be configured to send this signal to the process
+after a log rotation event has occurred.
+
+Given a similar scenario as in the [Log rotation](#rotate) section a basic
+`logrotate` config that aligns with this strategy would look similar to the following:
+
+```
+/var/log/myapp.log {
+       su root
+       daily
+       rotate 7
+       delaycompress
+       compress
+       notifempty
+       missingok
+       postrotate
+           kill -HUP `cat /var/run/myapp.pid`
+       endscript
+}
+```
+
+<a id="multiple"></a>
+## Saving to multiple files
+
+See [`pino.multistream`](/docs/api.md#pino-multistream).
+
+<a id="filter-logs"></a>
+## Log Filtering
+The Pino philosophy advocates common, preexisting, system utilities.
+
+Some recommendations in line with this philosophy are:
+
+1. Use [`grep`](https://linux.die.net/man/1/grep):
+    ```sh
+    $ # View all "INFO" level logs
+    $ node app.js | grep '"level":30'
+    ```
+1. Use [`jq`](https://stedolan.github.io/jq/):
+    ```sh
+    $ # View all "ERROR" level logs
+    $ node app.js | jq 'select(.level == 50)'
+    ```
+
+<a id="transport-systemd"></a>
+## Transports and systemd
+`systemd` makes it complicated to use pipes in services. One method for overcoming
+this challenge is to use a subshell:
+
+```
+ExecStart=/bin/sh -c '/path/to/node app.js | pino-transport'
+```
+
+<a id="multi-stream"></a>
+## Log to different streams
+
+Pino's default log destination is the singular destination of `stdout`. While
+not recommended for performance reasons, multiple destinations can be targeted
+by using [`pino.multistream`](/docs/api.md#pino-multistream).
+
+In this example, we use `stderr` for `error` level logs and `stdout` as default
+for all other levels (e.g. `debug`, `info`, and `warn`).
+
+```js
+const pino = require('pino')
+var streams = [
+  {level: 'debug', stream: process.stdout},
+  {level: 'error', stream: process.stderr},
+  {level: 'fatal', stream: process.stderr}
+]
+
+const logger = pino({
+  name: 'my-app',
+  level: 'debug', // must be the lowest level of all streams
+}, pino.multistream(streams))
+```
+
+<a id="dupe-keys"></a>
+## How Pino handles duplicate keys
+
+Duplicate keys are possibly when a child logger logs an object with a key that
+collides with a key in the child loggers bindings.
+
+See the [child logger duplicate keys caveat](/docs/child-loggers.md#duplicate-keys-caveat)
+for information on this is handled.
+
+<a id="level-string"></a>
+## Log levels as labels instead of numbers
+Pino log lines are meant to be parsable. Thus, Pino's default mode of operation
+is to print the level value instead of the string name. 
+However, you can use the [`formatters`](/docs/api.md#formatters-object) option 
+with a [`level`](/docs/api.md#level) function to print the string name instead of the level value :
+
+```js
+const pino = require('pino')
+
+const log = pino({
+  formatters: {
+    level: (label) => {
+      return {
+        level: label
+      }
+    }
+  }
+})
+
+log.info('message')
+
+// {"level":"info","time":1661632832200,"pid":18188,"hostname":"foo","msg":"message"}
+```
+
+Although it works, we recommend using one of these options instead if you are able:
+
+1. If the only change desired is the name then a transport can be used. One such
+transport is [`pino-text-level-transport`](https://npm.im/pino-text-level-transport).
+1. Use a prettifier like [`pino-pretty`](https://npm.im/pino-pretty) to make
+the logs human friendly.
+
+<a id="debug"></a>
+## Pino with `debug`
+
+The popular [`debug`](https://npm.im/debug) is used in many modules across the ecosystem.
+
+The [`pino-debug`](https://github.com/pinojs/pino-debug) module
+can capture calls to `debug` loggers and run them
+through `pino` instead. This results in a 10x (20x in asynchronous mode)
+performance improvement - even though `pino-debug` is logging additional
+data and wrapping it in JSON.
+
+To quickly enable this install [`pino-debug`](https://github.com/pinojs/pino-debug)
+and preload it with the `-r` flag, enabling any `debug` logs with the
+`DEBUG` environment variable:
+
+```sh
+$ npm i pino-debug
+$ DEBUG=* node -r pino-debug app.js
+```
+
+[`pino-debug`](https://github.com/pinojs/pino-debug) also offers fine-grain control to map specific `debug`
+namespaces to `pino` log levels. See [`pino-debug`](https://github.com/pinojs/pino-debug)
+for more.
+
+<a id="windows"></a>
+## Unicode and Windows terminal
+
+Pino uses [sonic-boom](https://github.com/mcollina/sonic-boom) to speed
+up logging. Internally, it uses [`fs.write`](https://nodejs.org/dist/latest-v10.x/docs/api/fs.html#fs_fs_write_fd_string_position_encoding_callback) to write log lines directly to a file
+descriptor. On Windows, Unicode output is not handled properly in the
+terminal (both `cmd.exe` and PowerShell), and as such the output could
+be visualized incorrectly if the log lines include utf8 characters. It
+is possible to configure the terminal to visualize those characters
+correctly with the use of [`chcp`](https://ss64.com/nt/chcp.html) by
+executing in the terminal `chcp 65001`. This is a known limitation of
+Node.js.
+
+<a id="stackdriver"></a>
+## Mapping Pino Log Levels to Google Cloud Logging (Stackdriver) Severity Levels
+
+Google Cloud Logging uses `severity` levels instead of log levels. As a result, all logs may show as INFO
+level logs while completely ignoring the level set in the pino log. Google Cloud Logging also prefers that
+log data is present inside a `message` key instead of the default `msg` key that Pino uses. Use a technique
+similar to the one below to retain log levels in Google Cloud Logging
+
+```js
+const pino = require('pino')
+
+// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
+const PinoLevelToSeverityLookup = {
+  trace: 'DEBUG',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+};
+
+const defaultPinoConf = {
+  messageKey: 'message',
+  formatters: {
+    level(label, number) {
+      return {
+        severity: PinoLevelToSeverityLookup[label] || PinoLevelToSeverityLookup['info'],
+        level: number,
+      }
+    }
+  },
+}
+
+module.exports = function createLogger(options) {
+  return pino(Object.assign({}, options, defaultPinoConf))
+}
+```
+
+A library that configures Pino for
+[Google Cloud Structured Logging](https://cloud.google.com/logging/docs/structured-logging)
+is available at:
+[@google-cloud/pino-logging-gcp-config](https://www.npmjs.com/package/@google-cloud/pino-logging-gcp-config)
+
+This library has the following features:
+
++ Converts Pino log levels to Google Cloud Logging log levels, as above
++ Uses `message` instead of `msg` for the message key, as above
++ Adds a millisecond-granularity timestamp in the 
+  [structure](https://cloud.google.com/logging/docs/agent/logging/configuration#timestamp-processing)
+  recognised by Google Cloud Logging eg: \
+  `"timestamp":{"seconds":1445470140,"nanos":123000000}`
++ Adds a sequential
+  [`insertId`](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#FIELDS.insert_id)
+  to ensure log messages with identical timestamps are ordered correctly.
++ Logs including an `Error` object have the
+  [`stack_trace`](https://cloud.google.com/error-reporting/docs/formatting-error-messages#log-error)
+  property set so that the error is forwarded to Google Cloud Error Reporting.
++ Includes a
+  [`ServiceContext`](https://cloud.google.com/error-reporting/reference/rest/v1beta1/ServiceContext)
+  object in the logs for Google Cloud Error Reporting, auto detected from the
+  environment if not specified
++ Maps the OpenTelemetry properties `span_id`, `trace_id`, and `trace_flags`
+  to the equivalent Google Cloud Logging fields.
+
+<a id="grafana-loki"></a>
+## Using Grafana Loki to evaluate pino logs in a kubernetes cluster
+
+To get pino logs into Grafana Loki there are two options:
+
+1. **Push:** Use [pino-loki](https://github.com/Julien-R44/pino-loki) to send logs directly to Loki.
+1. **Pull:** Configure Grafana Promtail to read and properly parse the logs before sending them to Loki.  
+   Similar to Google Cloud logging, this involves remapping the log levels. See this [article](https://medium.com/@janpaepke/structured-logging-in-the-grafana-monitoring-stack-8aff0a5af2f5) for details.
+
+<a id="avoid-message-conflict"></a>
+## Avoid Message Conflict
+
+As described in the [`message` documentation](/docs/api.md#message), when a log
+is written like `log.info({ msg: 'a message' }, 'another message')` then the
+final output JSON will have `"msg":"another message"` and the `'a message'`
+string will be lost. To overcome this, the [`logMethod` hook](/docs/api.md#logmethod)
+can be used:
+
+```js
+'use strict'
+
+const log = require('pino')({
+  level: 'debug',
+  hooks: {
+    logMethod (inputArgs, method) {
+      if (inputArgs.length === 2 && inputArgs[0].msg) {
+       inputArgs[0].originalMsg = inputArgs[0].msg
+      }
+      return method.apply(this, inputArgs)
+    }
+  }
+})
+
+log.info('no original message')
+log.info({ msg: 'mapped to originalMsg' }, 'a message')
+
+// {"level":30,"time":1596313323106,"pid":63739,"hostname":"foo","msg":"no original message"}
+// {"level":30,"time":1596313323107,"pid":63739,"hostname":"foo","msg":"a message","originalMsg":"mapped to originalMsg"}
+```
+
+<a id="best-performance-for-stdout"></a>
+## Best performance for logging to `stdout`
+
+The best performance for logging directly to stdout is _usually_ achieved by using the
+default configuration:
+
+```js
+const log = require('pino')();
+```
+
+You should only have to configure custom transports or other settings
+if you have broader logging requirements.
+
+<a id="testing"></a>
+## Testing
+
+See [`pino-test`](https://github.com/pinojs/pino-test).

package/node_modules/pino/docs/lts.md

@@ -0,0 +1,64 @@
+## Long Term Support
+
+Pino's Long Term Support (LTS) is provided according to the schedule laid
+out in this document:
+
+1. Major releases, "X" release of [semantic versioning][semver] X.Y.Z release
+   versions, are supported for a minimum period of six months from their release
+   date. The release date of any specific version can be found at
+   [https://github.com/pinojs/pino/releases](https://github.com/pinojs/pino/releases).
+
+1. Major releases will receive security updates for an additional six months
+   from the release of the next major release. After this period
+   we will still review and release security fixes as long as they are
+   provided by the community and they do not violate other constraints,
+   e.g. minimum supported Node.js version.
+
+1. Major releases will be tested and verified against all Node.js
+   release lines that are supported by the
+   [Node.js LTS policy](https://github.com/nodejs/Release) within the
+   LTS period of that given Pino release line. This implies that only
+   the latest Node.js release of a given line is supported.
+
+A "month" is defined as 30 consecutive days.
+
+> ## Security Releases and Semver
+>
+> As a consequence of providing long-term support for major releases, there
+> are occasions where we need to release breaking changes as a _minor_
+> version release. Such changes will _always_ be noted in the
+> [release notes](https://github.com/pinojs/pino/releases).
+>
+> To avoid automatically receiving breaking security updates it is possible to use
+> the tilde (`~`) range qualifier. For example, to get patches for the 6.1
+> release, and avoid automatically updating to the 6.1 release, specify
+> the dependency as `"pino": "~6.1.x"`. This will leave your application vulnerable,
+> so please use with caution.
+
+[semver]: https://semver.org/
+
+<a name="lts-schedule"></a>
+
+### Schedule
+
+| Version | Release Date | End Of LTS Date | Node.js              |
+| :------ | :----------- | :-------------- | :------------------- |
+| 9.x     | 2024-04-26   | TBD             | 18, 20, 22            |
+| 8.x     | 2022-06-01   | 2024-10-26      | 14, 16, 18, 20        |
+| 7.x     | 2021-10-14   | 2023-06-01      | 12, 14, 16           |
+| 6.x     | 2020-03-07   | 2022-04-14      | 10, 12, 14, 16       |
+
+<a name="supported-os"></a>
+
+### CI tested operating systems
+
+Pino uses GitHub Actions for CI testing, please refer to
+[GitHub's documentation regarding workflow runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)
+for further details on what the latest virtual environment is in relation to
+the YAML workflow labels below:
+
+| OS      | YAML Workflow Label    | Node.js      |
+|---------|------------------------|--------------|
+| Linux   | `ubuntu-latest`        | 18, 20, 22   |
+| Windows | `windows-latest`       | 18, 20, 22   |
+| MacOS   | `macos-latest`         | 18, 20, 22   |

package/node_modules/pino/docs/pretty.md

@@ -0,0 +1,35 @@
+# Pretty Printing
+
+By default, Pino log lines are newline delimited JSON (NDJSON). This is perfect
+for production usage and long-term storage. It's not so great for development
+environments. Thus, Pino logs can be prettified by using a Pino prettifier
+module like [`pino-pretty`][pp]:
+
+1. Install a prettifier module as a separate dependency, e.g. `npm install pino-pretty`.
+2. Instantiate the logger with the `transport.target` option set to `'pino-pretty'`:
+  ```js
+  const pino = require('pino')
+  const logger = pino({
+    transport: {
+      target: 'pino-pretty'
+    },
+  })
+
+  logger.info('hi')
+  ```
+3. The transport option can also have an options object containing `pino-pretty` options:
+  ```js
+  const pino = require('pino')
+  const logger = pino({
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true
+      }
+    }
+  })
+
+  logger.info('hi')
+  ```
+
+  [pp]: https://github.com/pinojs/pino-pretty

package/node_modules/pino/docs/redaction.md

@@ -0,0 +1,135 @@
+# Redaction
+
+> Redaction is not supported in the browser [#670](https://github.com/pinojs/pino/issues/670)
+
+To redact sensitive information, supply paths to keys that hold sensitive data
+using the `redact` option. Note that paths that contain hyphens need to use
+brackets to access the hyphenated property:
+
+```js
+const logger = require('.')({
+  redact: ['key', 'path.to.key', 'stuff.thats[*].secret', 'path["with-hyphen"]']
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output:
+
+```JSON
+{"level":30,"time":1527777350011,"pid":3186,"hostname":"Davids-MacBook-Pro-3.local","key":"[Redacted]","path":{"to":{"key":"[Redacted]","another":"thing"}},"stuff":{"thats":[{"secret":"[Redacted]","logme":"will be logged"},{"secret":"[Redacted]","logme":"as will this"}]}}
+```
+
+The `redact` option can take an array (as shown in the above example) or
+an object. This allows control over *how* information is redacted.
+
+For instance, setting the censor:
+
+```js
+const logger = require('.')({
+  redact: {
+    paths: ['key', 'path.to.key', 'stuff.thats[*].secret'],
+    censor: '**GDPR COMPLIANT**'
+  }
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output:
+
+```JSON
+{"level":30,"time":1527778563934,"pid":3847,"hostname":"Davids-MacBook-Pro-3.local","key":"**GDPR COMPLIANT**","path":{"to":{"key":"**GDPR COMPLIANT**","another":"thing"}},"stuff":{"thats":[{"secret":"**GDPR COMPLIANT**","logme":"will be logged"},{"secret":"**GDPR COMPLIANT**","logme":"as will this"}]}}
+```
+
+The `redact.remove` option also allows for the key and value to be removed from output:
+
+```js
+const logger = require('.')({
+  redact: {
+    paths: ['key', 'path.to.key', 'stuff.thats[*].secret'],
+    remove: true
+  }
+})
+
+logger.info({
+  key: 'will be redacted',
+  path: {
+    to: {key: 'sensitive', another: 'thing'}
+  },
+  stuff: {
+    thats: [
+      {secret: 'will be redacted', logme: 'will be logged'},
+      {secret: 'as will this', logme: 'as will this'}
+    ]
+  }
+})
+```
+
+This will output
+
+```JSON
+{"level":30,"time":1527782356751,"pid":5758,"hostname":"Davids-MacBook-Pro-3.local","path":{"to":{"another":"thing"}},"stuff":{"thats":[{"logme":"will be logged"},{"logme":"as will this"}]}}
+```
+
+See [pino options in API](/docs/api.md#redact-array-object) for `redact` API details.
+
+<a name="paths"></a>
+## Path Syntax
+
+The syntax for paths supplied to the `redact` option conform to the syntax in path lookups
+in standard ECMAScript, with two additions:
+
+* paths may start with bracket notation
+* paths may contain the asterisk `*` to denote a wildcard
+* paths are **case sensitive**
+
+By way of example, the following are all valid paths:
+
+* `a.b.c`
+* `a["b-c"].d`
+* `["a-b"].c`
+* `a.b.*`
+* `a[*].b`
+
+## Overhead
+
+Pino's redaction functionality is built on top of [`fast-redact`](https://github.com/davidmarkclements/fast-redact)
+which adds about 2% overhead to `JSON.stringify` when using paths without wildcards.
+
+When used with pino logger with a single redacted path, any overhead is within noise -
+a way to deterministically measure its effect has not been found. This is because it is not a bottleneck.
+
+However, wildcard redaction does carry a non-trivial cost relative to explicitly declaring the keys
+(50% in a case where four keys are redacted across two objects). See
+the [`fast-redact` benchmarks](https://github.com/davidmarkclements/fast-redact#benchmarks) for details.
+
+## Safety
+
+The `redact` option is intended as an initialization time configuration option.
+Path strings must not originate from user input.
+The `fast-redact` module uses a VM context to syntax check the paths, user input
+should never be combined with such an approach. See the [`fast-redact` Caveat](https://github.com/davidmarkclements/fast-redact#caveat)
+and the [`fast-redact` Approach](https://github.com/davidmarkclements/fast-redact#approach) for in-depth information.