pear-terminal 1.0.0 → 1.1.0

package/README.md

@@ -16,10 +16,9 @@ Ask user to trust or unlock an app/template.
 
 Returns `Promise<void>`.
 
-* `ipc`: `{ permit({ key, password? }), close() }`
-* `info`: `{ key: Buffer|string, encrypted: boolean }`
-* `cmd`: `'run'|'init'|'stage'|'seed'|'dump'|'info'`
-
+- `ipc`: `{ permit({ key, password? }), close() }`
+- `info`: `{ key: Buffer|string, encrypted: boolean }`
+- `cmd`: `'run'|'init'|'stage'|'seed'|'dump'|'info'`
 
 ### `confirm(dialog, ask, delim, validation, msg)`
 
@@ -27,20 +26,20 @@ One-shot confirmation prompt.
 
 Returns `Promise<void>`.
 
-* `dialog`: `string` preface text
-* `ask`: `string` prompt label
-* `delim`: `string` delimiter (e.g. `':'` or '?'`)
-* `validation`: `(value:string) => boolean|Promise<boolean>`
-* `msg`: `string` error message on invalid input
+- `dialog`: `string` preface text
+- `ask`: `string` prompt label
+- `delim`: `string` delimiter (e.g. `':'` or '?'`)
+- `validation`: `(value:string) => boolean|Promise<boolean>`
+- `msg`: `string` error message on invalid input
 
 ### `const interact = new Interact(header, params[, opts])`
 
 Interactive prompt runner.
 
-* `header`: `string` shown once before prompts
-* `params`: `Array<{ name, prompt, default?, delim?, validation?, msg?, shave? }>`
-* `opts.masked`: `boolean` mask user input (passwords)
-* `opts.defaults`: `{ [name:string]: any }` fallback values
+- `header`: `string` shown once before prompts
+- `params`: `Array<{ name, prompt, default?, delim?, validation?, msg?, shave? }>`
+- `opts.masked`: `boolean` mask user input (passwords)
+- `opts.defaults`: `{ [name:string]: any }` fallback values
 
 #### `interact.run([opts])`
 
@@ -48,7 +47,7 @@ Process prompts and return answers.
 
 Returns `Promise<{ fields, shave }>`.
 
-* `opts.autosubmit`: `boolean` fill with defaults without prompting
+- `opts.autosubmit`: `boolean` fill with defaults without prompting
 
 ### `stdio`
 
@@ -56,11 +55,11 @@ Thin stdio wrapper with Bare/TTY streams.
 
 Returns object with:
 
-* `in`, `out`, `err`: lazy streams
-* `size() -> { width, height }`
-* `raw(bool) -> void` set raw mode
-* `drained(stream) -> Promise<void>`
-* `inAttached`: `boolean`
+- `in`, `out`, `err`: lazy streams
+- `size() -> { width, height }`
+- `raw(bool) -> void` set raw mode
+- `drained(stream) -> Promise<void>`
+- `inAttached`: `boolean`
 
 ### `ansi`
 
@@ -68,10 +67,10 @@ ANSI styling helpers (no-op on Windows).
 
 Returns object with:
 
-* text: `bold, dim, italic, underline, inverse, red, green, yellow, gray`
-* cursor: `upHome(n)`, `hideCursor()`, `showCursor()`
-* links: `link(url, text?)`
-* glyphs: `sep, tick, cross, warning, pear, dot, key, down, up`
+- text: `bold, dim, italic, underline, inverse, red, green, yellow, gray`
+- cursor: `upHome(n)`, `hideCursor()`, `showCursor()`
+- links: `link(url, text?)`
+- glyphs: `sep, tick, cross, warning, pear, dot, key, down, up`
 
 ### `indicator(value[, type])`
 
@@ -79,8 +78,8 @@ Status glyph helper.
 
 Returns `string`.
 
-* `value`: `true|false|null|number` (`>0` success, `<0` fail, `0|null` neutral)
-* `type`: `'success'|'diff'` (`diff`: `+ | - | ~`)
+- `value`: `true|false|null|number` (`>0` success, `<0` fail, `0|null` neutral)
+- `type`: `'success'|'diff'` (`diff`: `+ | - | ~`)
 
 ### `status(message[, success])`
 
@@ -88,8 +87,8 @@ Live status line (TTY-aware).
 
 Returns `void`.
 
-* `message`: `string`
-* `success`: `boolean|null|number` (see `indicator`)
+- `message`: `string`
+- `success`: `boolean|null|number` (see `indicator`)
 
 ### `print(message[, success])`
 
@@ -97,8 +96,8 @@ Plain line print with optional status glyph.
 
 Returns `void`.
 
-* `message`: `string`
-* `success`: `boolean|null|number`
+- `message`: `string`
+- `success`: `boolean|null|number`
 
 ### `byteDiff({ type, sizes, message })`
 
@@ -106,9 +105,9 @@ Pretty-print byte deltas.
 
 Returns `void`.
 
-* `type`: any value passed to `indicator(..., 'diff')`
-* `sizes`: `number[]` byte changes (signed)
-* `message`: `string`
+- `type`: any value passed to `indicator(..., 'diff')`
+- `sizes`: `number[]` byte changes (signed)
+- `message`: `string`
 
 ### `outputter(cmd[, taggers])`
 
@@ -116,23 +115,32 @@ Create a stream consumer that routes tagged events to `print/status` (TTY) or JS
 
 Returns `(opts, stream, info?, ipc?) -> Promise<void>`.
 
-* `cmd`: `string` command name
-* `taggers`: `{ [tag]: (data, info, ipc) => string|{ output, message, success }|false|Promise<...> }`
-  * `output`: `'print'|'status'`
-  * `message`: `string|string[]`
-  * `success`: `boolean`
-* `opts`: `{ json?: boolean, log?: (msg, { output, success? }) => void, ctrlTTY?: boolean }`
-* `stream`: `Readable|Array` of `{ tag, data }` events
-* `info`: any extra context
-* `ipc`: optional IPC handle
+- `cmd`: `string` command name
+- `taggers`: `{ [tag]: (data, info, ipc) => string|{ output, message, success }|false|Promise<...> }`
+  - `output`: `'print'|'status'`
+  - `message`: `string|string[]`
+  - `success`: `boolean`
+- `opts`: `{ json?: boolean, log?: (msg, { output, success? }) => void, ctrlTTY?: boolean }`
+- `stream`: `Readable|Array` of `{ tag, data }` events
+- `info`: any extra context
+- `ipc`: optional IPC handle
 
 Behavior:
+
 - `opts.json === true` → emits JSON lines: `{ cmd, tag, data }`
 - `tagger` result `false`:
   - for `tag==='final'` prints default success/failure
   - otherwise suppressed
 - TTY: hides/shows cursor, handles Ctrl+C cleanup
 
+### `explain(bail)`
+
+Processes failure mode flow for various Pear scenarios that prints sensible output showing stacks for operational errors and beautified output user errors.
+
+Returns `void`.
+
+- `bail`: a [paparam](https://github.com/holepunchto/paparam) bail object
+
 ### `isTTY`
 
 `boolean` indicating stdin TTY status.
@@ -145,4 +153,4 @@ Returns `string`.
 
 ## License
 
-Apache-2.0
+Apache-2.0

package/index.js

@@ -1,23 +1,42 @@
 'use strict'
-/* global Bare */
+
 const readline = require('bare-readline')
 const tty = require('bare-tty')
 const fs = require('bare-fs')
-const { Writable, Readable } = require('streamx')
+const os = require('bare-os')
 const { Writable: BareWritable, Readable: BareReadable } = require('bare-stream')
-const { once } = require('bare-events')
+const { Writable, Readable } = require('streamx')
 const hypercoreid = require('hypercore-id-encoding')
 const byteSize = require('tiny-byte-size')
 const { isWindows } = require('which-runtime')
 const { CHECKOUT } = require('pear-constants')
 const gracedown = require('pear-gracedown')
+const errors = require('pear-errors')
 const opwait = require('pear-opwait')
 const isTTY = tty.isTTY(0)
 
+function ERR_SIGINT(msg) {
+  return new errors(msg, ERR_SIGINT)
+}
+
 const pt = (arg) => arg
 const es = () => ''
 const ansi = isWindows
-  ? { bold: pt, dim: pt, italic: pt, underline: pt, inverse: pt, red: pt, green: pt, yellow: pt, gray: pt, upHome: es, link: pt, hideCursor: es, showCursor: es }
+  ? {
+      bold: pt,
+      dim: pt,
+      italic: pt,
+      underline: pt,
+      inverse: pt,
+      red: pt,
+      green: pt,
+      yellow: pt,
+      gray: pt,
+      upHome: es,
+      link: pt,
+      hideCursor: es,
+      showCursor: es
+    }
   : {
       bold: (s) => `\x1B[1m${s}\x1B[22m`,
       dim: (s) => `\x1B[2m${s}\x1B[22m`,
@@ -39,30 +58,36 @@ ansi.tick = isWindows ? '^' : ansi.green('✔')
 ansi.cross = isWindows ? 'x' : ansi.red('✖')
 ansi.warning = isWindows ? '!' : '⚠️'
 ansi.pear = isWindows ? '*' : '🍐'
-ansi.dot = isWindows ? '•' : 'o'
+ansi.dot = isWindows ? 'o' : '•'
 ansi.key = isWindows ? '>' : '🔑'
 ansi.down = isWindows ? '↓' : '⬇'
 ansi.up = isWindows ? '↑' : '⬆'
 
-const stdio = new class Stdio {
+const stdio = new (class Stdio {
   static WriteStream = class FdWriteStream extends BareWritable {
-    constructor (fd) {
-      super({ map: (data) => typeof data === 'string' ? Buffer.from(data) : data })
+    constructor(fd) {
+      super({
+        map: (data) => (typeof data === 'string' ? Buffer.from(data) : data)
+      })
       this.fd = fd
     }
 
-    _writev (batch, cb) {
-      fs.writev(this.fd, batch.map(({ chunk }) => chunk), cb)
+    _writev(batch, cb) {
+      fs.writev(
+        this.fd,
+        batch.map(({ chunk }) => chunk),
+        cb
+      )
     }
   }
 
   static ReadStream = class FdReadStream extends BareReadable {
-    constructor (fd) {
+    constructor(fd) {
       super()
       this.fd = fd
     }
 
-    _read (size) {
+    _read(size) {
       const buffer = Buffer.alloc(size)
       fs.read(this.fd, buffer, 0, size, null, (err, bytesRead) => {
         if (err) return this.destroy(err)
@@ -73,57 +98,71 @@ const stdio = new class Stdio {
   }
 
   drained = Writable.drained
-  constructor () {
+  constructor() {
     this._in = null
     this._out = null
     this._err = null
     this.rawMode = false
   }
 
-  get inAttached () { return this._in !== null }
+  get inAttached() {
+    return this._in !== null
+  }
 
-  get in () {
+  get in() {
     if (this._in === null) {
       this._in = tty.isTTY(0) ? new tty.ReadStream(0) : new this.constructor.ReadStream(0)
-      this._in.once('close', () => { this._in = null })
+      this._in.once('close', () => {
+        this._in = null
+      })
     }
     return this._in
   }
 
-  get out () {
-    if (this._out === null) this._out = tty.isTTY(1) ? new tty.WriteStream(1) : new this.constructor.WriteStream(1)
+  get out() {
+    if (this._out === null) {
+      this._out = tty.isTTY(1) ? new tty.WriteStream(1) : new this.constructor.WriteStream(1)
+    }
     return this._out
   }
 
-  get err () {
-    if (this._err === null) this._err = tty.isTTY(2) ? new tty.WriteStream(2) : new this.constructor.WriteStream(2)
+  get err() {
+    if (this._err === null) {
+      this._err = tty.isTTY(2) ? new tty.WriteStream(2) : new this.constructor.WriteStream(2)
+    }
     return this._err
   }
 
-  size () {
+  size() {
     if (!this.out.getWindowSize) return [80, 80]
     const [width, height] = this.out.getWindowSize()
     return { width, height }
   }
 
-  raw (rawMode) {
+  raw(rawMode) {
     this.rawMode = !!rawMode
-    return this.in.setMode?.(this.rawMode ? this.tty.constants.MODE_RAW : this.tty.constants.MODE_NORMAL)
+    return this.in.setMode?.(
+      this.rawMode ? this.tty.constants.MODE_RAW : this.tty.constants.MODE_NORMAL
+    )
   }
-}()
+})()
 
 class Interact {
-  static rx = /[\x1B\x9B][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\x07)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g // eslint-disable-line no-control-regex
-  constructor (header, params, opts = {}) {
+  static rx =
+    /[\x1B\x9B][[\]()#;?]*(?:(?:(?:(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*|[a-zA-Z\d]+(?:;[-a-zA-Z\d/#&.:=?%@~_]*)*)?\x07)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g // eslint-disable-line no-control-regex
+  constructor(header, params, opts = {}) {
     this._header = header
     this._params = params
     this._defaults = opts.defaults || {}
 
     const mask = (data, cb) => {
-      if (data.length > 4) { // is full line
+      if (data.length > 4) {
+        // is full line
         const prompt = this._rl._prompt
         const regex = new RegExp(`(${prompt})([\\x20-\\x7E]+)`, 'g') // match printable chars after prompt
-        const masked = data.toString().replace(regex, (_, prompt, pwd) => prompt + '*'.repeat(pwd.length))
+        const masked = data
+          .toString()
+          .replace(regex, (_, prompt, pwd) => prompt + '*'.repeat(pwd.length))
         stdio.out.write(masked)
       } else {
         stdio.out.write(data)
@@ -135,15 +174,13 @@ class Interact {
       input: stdio.in,
       output: opts.masked ? new Writable({ write: mask }) : stdio.out
     })
-
-    this._rl.input?.setMode?.(tty.constants.MODE_RAW)
     this._rl.on('close', () => {
-      console.log() // new line
-      Bare.exit()
+      console.log() // newline
     })
+    stdio.in?.setMode?.(tty.constants.MODE_RAW)
   }
 
-  async run (opts) {
+  async run(opts) {
     try {
       return await this.#run(opts)
     } finally {
@@ -151,7 +188,7 @@ class Interact {
     }
   }
 
-  async #run (opts = {}) {
+  async #run(opts = {}) {
     if (opts.autosubmit) return this.#autosubmit()
     stdio.out.write(this._header)
     const fields = {}
@@ -161,13 +198,16 @@ class Interact {
       const param = this._params.shift()
       while (true) {
         const deflt = defaults[param.name] ?? param.default
-        let answer = await this.#input(`${param.prompt}${param.delim || ':'}${deflt && ' (' + deflt + ')'} `)
-
+        let answer = await this.#input(
+          `${param.prompt}${param.delim || ':'}${deflt && ' (' + deflt + ')'} `
+        )
         if (answer.length === 0) answer = defaults[param.name] ?? deflt
-        if (!param.validation || await param.validation(answer)) {
+        if (!param.validation || (await param.validation(answer))) {
           if (typeof answer === 'string') answer = answer.replace(this.constructor.rx, '')
           fields[param.name] = answer
-          if (Array.isArray(param.shave) && param.shave.every((ix) => typeof ix === 'number')) shave[param.name] = param.shave
+          if (Array.isArray(param.shave) && param.shave.every((ix) => typeof ix === 'number')) {
+            shave[param.name] = param.shave
+          }
           break
         } else {
           stdio.out.write(param.msg + '\n')
@@ -177,112 +217,144 @@ class Interact {
     return { fields, shave }
   }
 
-  #autosubmit () {
+  #autosubmit() {
     const fields = {}
     const shave = {}
     const defaults = this._defaults
     while (this._params.length) {
       const param = this._params.shift()
       fields[param.name] = defaults[param.name] ?? param.default
-      if (Array.isArray(param.shave) && param.shave.every((ix) => typeof ix === 'number')) shave[param.name] = param.shave
+      if (Array.isArray(param.shave) && param.shave.every((ix) => typeof ix === 'number')) {
+        shave[param.name] = param.shave
+      }
     }
     return { fields, shave }
   }
 
-  async #input (prompt) {
+  async #input(prompt) {
     stdio.out.write(prompt)
     this._rl._prompt = prompt
-    const answer = (await once(this._rl, 'data')).toString()
-    return answer.trim() // remove return char
+    const answer = await new Promise((resolve, reject) => {
+      this._rl.once('data', (data) => {
+        resolve(data)
+      })
+      stdio.in?.once('data', (data) => {
+        if (data.length === 1 && data[0] === 3) {
+          reject(ERR_SIGINT('^C exit'))
+          os.kill(Pear.pid, 'SIGINT')
+        }
+      })
+    })
+    return answer.toString().trim() // remove return char
   }
 }
 
 let statusFrag = ''
 
-function status (msg, success) {
+function status(msg, success) {
   msg = msg || ''
   const done = typeof success === 'boolean'
   if (msg) stdio.out.write(`\x1B[2K\r${indicator(success)}${msg}\n${done ? '' : ansi.upHome()}`)
   statusFrag = msg.slice(0, 3)
 }
 
-function print (message, success) {
+function print(message, success) {
   statusFrag = ''
   console.log(`${typeof success !== 'undefined' ? indicator(success) : ''}${message}`)
 }
 
-function byteDiff ({ type, sizes, message }) {
+function byteDiff({ type, sizes, message }) {
   statusFrag = ''
   sizes = sizes.map((size) => (size > 0 ? '+' : '') + byteSize(size)).join(', ')
   print(indicator(type, 'diff') + ' ' + message + ' (' + sizes + ')')
 }
 
-function indicator (value, type = 'success') {
+function indicator(value, type = 'success') {
   if (value === undefined) return ''
   if (value === true) value = 1
   else if (value === false) value = -1
-  else if (value == null) value = 0
-  if (type === 'diff') return value === 0 ? ansi.yellow('~') : (value === 1 ? ansi.green('+') : ansi.red('-'))
-  return value < 0 ? ansi.cross + ' ' : (value > 0 ? ansi.tick + ' ' : ansi.gray('- '))
+  else if (value === null) value = 0
+  if (type === 'diff') {
+    return value === 0 ? ansi.yellow('~') : value === 1 ? ansi.green('+') : ansi.red('-')
+  }
+  return value < 0 ? ansi.cross + ' ' : value > 0 ? ansi.tick + ' ' : ansi.gray('- ')
 }
 
-const outputter = (cmd, taggers = {}) => (opts, stream, info = {}, ipc) => {
-  if (Array.isArray(stream)) stream = Readable.from(stream)
-  const asTTY = opts.ctrlTTY ?? isTTY
-  if (asTTY) stdio.out.write(ansi.hideCursor())
-  const dereg = asTTY
-    ? gracedown(() => {
-      if (!isWindows) stdio.out.write('\x1B[1K\x1B[G' + statusFrag) // clear ^C
-      stdio.out.write(ansi.showCursor())
-    })
-    : null
-  if (typeof opts === 'boolean') opts = { json: opts }
-  const { json = false, log } = opts
-  const promise = opwait(stream, ({ tag, data }) => {
-    if (json) {
-      const str = JSON.stringify({ cmd, tag, data })
-      if (log) log(str)
-      else print(str)
-      return
-    }
-
-    const transform = Promise.resolve(typeof taggers[tag] === 'function' ? taggers[tag](data, info, ipc) : taggers[tag] || false)
-    transform.then((result) => {
-      if (result === undefined) return
-      if (typeof result === 'string') result = { output: 'print', message: result }
-      if (result === false) {
-        if (tag === 'final') result = { output: 'print', message: (data.message ?? data.success ? 'Success' : 'Failure') }
-        else result = {}
-      }
-      result.success = result.success ?? data?.success
-      const { output, message, success = data?.success } = result
-      if (log) {
-        const logOpts = { output, ...(typeof success === 'boolean' ? { success } : {}) }
-        if (Array.isArray(message) === false) log(message, logOpts)
-        else for (const msg of message) log(msg, logOpts)
+const outputter =
+  (cmd, taggers = {}) =>
+  (opts, stream, info = {}, ipc) => {
+    if (Array.isArray(stream)) stream = Readable.from(stream)
+    const asTTY = opts.ctrlTTY ?? isTTY
+    if (asTTY) stdio.out.write(ansi.hideCursor())
+    const dereg = asTTY
+      ? gracedown(() => {
+          if (!isWindows) stdio.out.write('\x1B[1K\x1B[G' + statusFrag) // clear ^C
+          stdio.out.write(ansi.showCursor())
+        })
+      : null
+    if (typeof opts === 'boolean') opts = { json: opts }
+    const { json = false, log } = opts
+    const promise = opwait(stream, ({ tag, data }) => {
+      if (json) {
+        const str = JSON.stringify({ cmd, tag, data })
+        if (log) log(str)
+        else print(str)
         return
       }
-      let msg = Array.isArray(message) ? message.join('\n') : message
-      if (tag === 'final') msg += '\n'
-      if (output === 'print') print(msg, success)
-      if (output === 'status') status(msg, success)
-    }, (err) => stream.destroy(err))
-  })
-
-  return !asTTY
-    ? promise
-    : promise.finally(() => {
-      stdio.out.write(ansi.showCursor())
-      dereg(false)
+
+      const transform = Promise.resolve(
+        typeof taggers[tag] === 'function' ? taggers[tag](data, info, ipc) : taggers[tag] || false
+      )
+      transform.then(
+        (result) => {
+          if (result === undefined) return
+          if (typeof result === 'string') result = { output: 'print', message: result }
+          if (result === false) {
+            if (tag === 'final') {
+              result = {
+                output: 'print',
+                message: (data.message ?? data.success) ? 'Success' : 'Failure'
+              }
+            } else result = {}
+          }
+          result.success = result.success ?? data?.success
+          const { output, message, success = data?.success } = result
+          if (log) {
+            const logOpts = { output, ...(typeof success === 'boolean' ? { success } : {}) }
+            if (Array.isArray(message) === false) log(message, logOpts)
+            else for (const msg of message) log(msg, logOpts)
+            return
+          }
+          let msg = Array.isArray(message) ? message.join('\n') : message
+          if (tag === 'final') {
+            msg += '\n'
+            if (asTTY) {
+              stdio.out.write(ansi.showCursor())
+              dereg(false)
+            }
+          }
+
+          if (output === 'print') print(msg, success)
+          else if (output === 'status') status(msg, success)
+        },
+        (err) => stream.destroy(err)
+      )
     })
-}
+
+    return promise
+  }
 
 const banner = `${ansi.bold('Pear')} ~ ${ansi.dim('Welcome to the Internet of Peers')}`
 const version = `${CHECKOUT.fork || 0}.${CHECKOUT.length || 'dev'}.${CHECKOUT.key}`
 const header = `  ${banner}
   ${ansi.pear + ' '}${ansi.bold(ansi.gray('v' + version))}
 `
-const urls = ansi.link('https://pears.com', 'pears.com') + ' | ' + ansi.link('https://holepunch.to', 'holepunch.to') + ' | ' + ansi.link('https://keet.io', 'keet.io')
+const urls =
+  ansi.link('https://pears.com', 'pears.com') +
+  ' | ' +
+  ansi.link('https://holepunch.to', 'holepunch.to') +
+  ' | ' +
+  ansi.link('https://keet.io', 'keet.io')
 
 const footer = {
   overview: `  ${ansi.bold('Legend:')} [arg] = optional, <arg> = required, | = or \n  Run ${ansi.bold('pear help')} to output full help for all commands\n  For command help: ${ansi.bold('pear help [cmd]')} or ${ansi.bold('pear [cmd] -h')}\n
@@ -294,11 +366,13 @@ ${urls}\n${ansi.bold(ansi.dim('Pear'))} ~ ${ansi.dim('Welcome to the IoP')}
 
 const usage = { header, version, banner, footer }
 
-async function trust (ipc, key, cmd) {
+async function trust(ipc, key, cmd) {
   const explain = {
-    run: 'Be sure that software is trusted before running it\n' +
+    run:
+      'Be sure that software is trusted before running it\n' +
       '\nType "TRUST" to allow execution or anything else to exit\n\n',
-    init: 'This template is not trusted.\n' +
+    init:
+      'This template is not trusted.\n' +
       '\nType "TRUST" to trust this template, or anything else to exit\n\n'
   }
 
@@ -337,22 +411,20 @@ async function trust (ipc, key, cmd) {
   Bare.exit()
 }
 
-async function password (ipc, key, cmd) {
+async function password(ipc, key, cmd) {
   const z32 = hypercoreid.normalize(key)
 
   const explain = {
-    run: 'pear://' + z32 + ' is an encrypted application. \n' +
+    run:
+      'pear://' +
+      z32 +
+      ' is an encrypted application. \n' +
       '\nEnter the password to run the app.\n\n',
-    stage: 'This application is encrypted.\n' +
-        '\nEnter the password to stage the app.\n\n',
-    seed: 'This application is encrypted.\n' +
-        '\nEnter the password to seed the app.\n\n',
-    dump: 'This application is encrypted.\n' +
-        '\nEnter the password to dump the app.\n\n',
-    init: 'This template is encrypted.\n' +
-      '\nEnter the password to init from the template.\n\n',
-    info: 'This application is encrypted.\n' +
-      '\nEnter the password to retrieve info.\n\n'
+    stage: 'This application is encrypted.\n' + '\nEnter the password to stage the app.\n\n',
+    seed: 'This application is encrypted.\n' + '\nEnter the password to seed the app.\n\n',
+    dump: 'This application is encrypted.\n' + '\nEnter the password to dump the app.\n\n',
+    init: 'This template is encrypted.\n' + '\nEnter the password to init from the template.\n\n',
+    info: 'This application is encrypted.\n' + '\nEnter the password to retrieve info.\n\n'
   }
 
   const message = {
@@ -369,16 +441,20 @@ async function password (ipc, key, cmd) {
   const delim = ':'
   const validation = (key) => key.length > 0
   const msg = '\nPlease, enter a valid password.\n'
-  const interact = new Interact(dialog, [
-    {
-      name: 'value',
-      default: '',
-      prompt: ask,
-      delim,
-      validation,
-      msg
-    }
-  ], { masked: true })
+  const interact = new Interact(
+    dialog,
+    [
+      {
+        name: 'value',
+        default: '',
+        prompt: ask,
+        delim,
+        validation,
+        msg
+      }
+    ],
+    { masked: true }
+  )
   const { fields } = await interact.run()
   print(`\n${ansi.key} Hashing password...`)
   await ipc.permit({ key, password: fields.value })
@@ -387,7 +463,7 @@ async function password (ipc, key, cmd) {
   Bare.exit()
 }
 
-function permit (ipc, info, cmd) {
+function permit(ipc, info, cmd) {
   const key = info.key
   if (info.encrypted) {
     return password(ipc, key, cmd)
@@ -396,7 +472,7 @@ function permit (ipc, info, cmd) {
   }
 }
 
-async function confirm (dialog, ask, delim, validation, msg) {
+async function confirm(dialog, ask, delim, validation, msg) {
   const interact = new Interact(dialog, [
     {
       name: 'value',
@@ -410,4 +486,62 @@ async function confirm (dialog, ask, delim, validation, msg) {
   await interact.run()
 }
 
-module.exports = { usage, permit, stdio, ansi, indicator, status, print, outputter, isTTY, confirm, byteSize, byteDiff, Interact }
+function explain(bail = {}) {
+  if (!bail.reason && bail.err) {
+    const known = errors.known()
+    if (known.includes(bail.err.code) === false) {
+      print(
+        errors.ERR_UNKNOWN(
+          'Unknown [ code: ' + (bail.err.code || '(none)') + ' ] ' + bail.err.stack
+        ),
+        false
+      )
+      Bare.exit(1)
+    }
+  }
+  const messageUsage = (bail) => bail.err.message
+  const messageOnly = (bail) => bail.err.message
+  const opFail = (cmd) => cmd.err.info.message
+  const codemap = new Map([
+    ['UNKNOWN_FLAG', (bail) => 'Unrecognized Flag: --' + bail.flag.name],
+    [
+      'UNKNOWN_ARG',
+      (bail) => 'Unrecognized Argument at index ' + bail.arg.index + ' with value ' + bail.arg.value
+    ],
+    ['MISSING_ARG', (bail) => bail.arg.value],
+    ['INVALID', messageUsage],
+    ['ERR_INVALID_INPUT', messageUsage],
+    ['ERR_LEGACY', messageOnly],
+    ['ERR_INVALID_TEMPLATE', messageOnly],
+    ['ERR_DIR_NONEMPTY', messageOnly],
+    ['ERR_OPERATION_FAILED', opFail]
+  ])
+  const nouse = [messageOnly, opFail]
+  const code = codemap.has(bail.err?.code) ? bail.err.code : bail.reason
+  const ref = codemap.get(code)
+  const reason = codemap.has(code) ? (codemap.get(code)(bail) ?? bail.reason) : bail.reason
+  Bare.exitCode = 1
+
+  print(reason, false)
+
+  if (nouse.some((fn) => fn === ref) || codemap.has(code) === false) return
+
+  print('\n' + bail.command.usage())
+}
+
+module.exports = {
+  explain,
+  usage,
+  permit,
+  stdio,
+  ansi,
+  indicator,
+  status,
+  print,
+  outputter,
+  isTTY,
+  confirm,
+  byteSize,
+  byteDiff,
+  Interact
+}

package/package.json

@@ -1,22 +1,33 @@
 {
   "name": "pear-terminal",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Pear Terminal User Interface library",
   "license": "Apache-2.0",
   "files": [],
+  "imports": {
+    "process": {
+      "bare": "bare-process",
+      "default": "process"
+    }
+  },
   "scripts": {
+    "format": "prettier --write .",
+    "lint": "prettier --check . && lunte",
     "test:gen": "brittle -r test/all.js test/*.test.js",
-    "test": "brittle-bare --coverage test/all.js",
-    "lint": "standard"
+    "test": "brittle-bare test/all.js",
+    "test:bare": "brittle-bare test/all.js"
   },
   "devDependencies": {
     "bare-module": "^5.0.2",
-    "bare-os": "^3.6.1",
+    "bare-os": "^3.6.2",
+    "bare-process": "^4.2.2",
     "brittle": "^3.0.0",
+    "lunte": "^1.0.0",
     "pear-ipc": "^5.5.0",
-    "standard": "^17.1.2"
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
   },
   "dependencies": {
     "bare-events": "^2.6.1",
@@ -26,6 +37,7 @@
     "bare-tty": "^5.0.2",
     "hypercore-id-encoding": "^1.3.0",
     "pear-constants": "^1.0.0",
+    "pear-errors": "^1.0.1",
     "pear-gracedown": "^1.0.0",
     "pear-opwait": "^1.0.0",
     "streamx": "^2.22.1",