bare-tui-updater 0.0.0 → 0.0.1

package/README.md

@@ -0,0 +1,172 @@
+# bare-tui-updater
+
+A drop-in "update available" status-line widget for [bare-tui](https://github.com/holepunchto/bare-tui) apps using [pear-runtime](https://docs.pears.com/)'s OTA updater.
+
+Provides an unobtrusive one-line banner notification styled after Claude Code's CLI update flow: a user-controlled confirm gate before applying an update, visual progress during download/apply, and a restart prompt.
+
+## Install
+
+```sh
+npm install bare-tui-updater
+```
+
+## Quick Start
+
+```js
+const { Program, quit, key, style } = require('bare-tui')
+const updater = require('bare-tui-updater')
+const { wire } = require('bare-tui-updater/pear')
+
+const pear = new PearRuntime({ ... })
+
+class App {
+  constructor() {
+    this.upd = updater.create({
+      mode: 'confirm',
+      onAccept: async () => {
+        await pear.updater.applyUpdate()
+      }
+    })
+  }
+  update(msg) {
+    if (key.matches(msg, 'ctrl+c')) return [this, quit]
+    const [u, cmd] = this.upd.update(msg)
+    this.upd = u
+    return [this, cmd]
+  }
+  view() {
+    return style.joinVertical(style.position.left,
+      'My app...',
+      this.upd.view()
+    )
+  }
+}
+
+const program = new Program(new App())
+wire(this.upd, { updater: pear.updater, send: program.send.bind(program) })
+program.run()
+```
+
+## API
+
+### `updater.create(opts)`
+
+Returns a bare-tui component (`{ update(msg), view() }`).
+
+**Options:**
+
+- `mode` — `'confirm'` (default) | `'silent'` | `'notify-only'`
+  - **confirm**: download happens silently; once staged, a banner appears and the user presses a key to apply.
+  - **silent**: apply immediately on ready, no user interaction for apply (still shows "restart" prompt after apply).
+  - **notify-only**: user must call `applyUpdate()` themselves; widget only narrates the lifecycle.
+- `onAccept` — `async () => void` (required for `'confirm'`/`'silent'` modes)
+  - Called when the user accepts an update (or immediately in `'silent'` mode). Should call `await pear.updater.applyUpdate()` (or equivalent).
+- `acceptKey` — string, default `'u'` — the key to press to apply a ready update.
+- `dismissible` — boolean, default `true` — whether `esc` can dismiss the banner.
+- `autoDismissMs` — number, default `0` (never auto-dismiss) — hide the banner after N milliseconds in `applied`/`error` states.
+- `showProgress` — boolean, default `true` — show a spinner during download.
+- `width` — number, default `60` — max width of the banner (truncates with `…`).
+- `theme` — object — style overrides (see [theme.js](./theme.js)).
+- `copy` — object — text overrides for every message.
+
+**Component API:**
+
+- `update(msg)` — `(model, cmd)` — processes a Msg and returns the updated model + a Cmd.
+- `view()` — `string` — renders to a single line or `''` (empty when idle).
+- `focus()` / `blur()` — gates key handling.
+
+### `wire(widget, { updater, send })`
+
+Connects a widget to a pear-runtime `updater` instance.
+
+- `updater` — an EventEmitter with `.on('updating'|'updating-delta'|'updated'|'error')` (i.e., `pear.updater`).
+- `send` — function to inject Msgs into the bare-tui Program (i.e., `program.send.bind(program)`).
+
+Returns a `detach()` function to unsubscribe.
+
+```js
+const detach = wire(this.upd, { updater: pear.updater, send: program.send })
+// later...
+detach()
+```
+
+### `mock.mock()`
+
+Returns a fake updater for demos and tests. Useful because `pear-runtime-updater.applyUpdate()` silently no-ops outside a bundled build.
+
+```js
+const { mock } = require('bare-tui-updater/mock')
+const mockUpd = mock()
+await mockUpd.download({ version: '1.2.3' })
+await mockUpd.apply()
+```
+
+## Message Types
+
+The widget consumes these Msg types (produced by the `wire()` adapter or emitted manually):
+
+| Msg                                  | Meaning                                        |
+| ------------------------------------ | ---------------------------------------------- |
+| `{ type: 'update.downloading' }`     | Update download started.                       |
+| `{ type: 'update.progress', delta }` | One Hyperdrive mirror diff (raw pass-through). |
+| `{ type: 'update.ready', version }`  | New build staged on disk, awaiting apply.      |
+| `{ type: 'update.error', error }`    | Download/apply error.                          |
+| `{ type: 'update.apply' }`           | Internal: user pressed accept key.             |
+| `{ type: 'update.applied', runId }`  | Internal: apply finished.                      |
+| `{ type: 'update.dismiss' }`         | User pressed escape.                           |
+| `{ type: 'key' }`                    | Keyboard input (from bare-tui).                |
+
+## Layout Behavior
+
+The widget's `view()` returns either `''` (when idle) or a 3-line bordered block. This is non-intrusive by default: plan your layout for a **3-row insertion/removal when an update is available, and 0 rows the rest of the time**.
+
+**Critical:** `style.joinVertical` reserves one row per argument regardless of content — an empty string still becomes a blank padded line. To prevent a permanent blank row at idle, **filter out falsy/empty segments before joining**:
+
+```js
+view() {
+  return style.joinVertical(
+    style.position.left,
+    ...[
+      this._header(),      // fixed height
+      this._body(),        // fixed height
+      this.upd.view(),     // 3 lines (active) or '' (idle)
+      this._footer()       // fixed height
+    ].filter(Boolean)       // Drop empty strings so idle = 0 rows
+  )
+}
+```
+
+Without `.filter(Boolean)`, the widget reserves a permanent blank line in the layout — not intrusive once you know it's there, but not the zero-rows-at-idle behavior. With the filter, the update notification inserts/removes a 3-line block cleanly as needed.
+
+## Restart Handling
+
+**The widget does not restart the process automatically.** After applying an update, it displays "restart to use it" and the user/shell is responsible for relaunching the CLI.
+
+This is intentional: there is no cross-platform restart primitive in `pear-runtime`, and safe restart logic depends heavily on whether the app is a standalone `bare-build` binary (re-exec `Bare.argv[0]`) or running from source (`bare bin.js`, cannot safely restart itself). The decision is yours.
+
+A simple re-exec pattern (for standalone binaries):
+
+```js
+const { spawn } = require('bare-subprocess')
+
+async function restart() {
+  const child = spawn(Bare.argv[0], Bare.argv.slice(1), {
+    detached: true,
+    stdio: 'inherit'
+  })
+  child.unref()
+  await new Promise((r) => setImmediate(r))
+  Bare.exit(0)
+}
+```
+
+Wire this into your app's menu or call it after `onAccept` if you want automatic restart. See [examples/pear.js](./examples/pear.js) for a complete integration.
+
+## Examples
+
+- [minimal.js](./examples/minimal.js) — Smallest runnable demo with the mock updater.
+- [pear.js](./examples/pear.js) — Full integration with a real `pear-runtime` instance.
+
+## License
+
+Apache-2.0

package/index.js

@@ -0,0 +1,10 @@
+const { create, Updater } = require('./updater')
+const { defaultCopy } = require('./updater')
+const theme = require('./theme')
+
+module.exports = {
+  create,
+  Updater,
+  theme,
+  defaultCopy
+}

package/mock.js

@@ -0,0 +1,57 @@
+const { EventEmitter } = require('bare-events')
+
+function mock() {
+  const emitter = new EventEmitter()
+
+  emitter.nextVersion = null
+  emitter.updated = false
+  emitter.updating = false
+  emitter.bundled = true
+
+  emitter.download = async (opts = {}) => {
+    if (emitter.updated) return emitter
+    emitter.updating = true
+    emitter.emit('updating')
+
+    const delayMs = opts.delayMs || 1000
+    const deltaCount = opts.deltaCount || 3
+    const deltaDelayMs = delayMs / deltaCount
+
+    for (let i = 0; i < deltaCount; i++) {
+      await new Promise((resolve) => setTimeout(resolve, deltaDelayMs))
+      emitter.emit('updating-delta', { op: 'add', bytesAdded: 1024 * 100 })
+    }
+
+    emitter.updating = false
+    emitter.updated = true
+    emitter.nextVersion = opts.version || '1.2.3'
+    emitter.emit('updated')
+    return emitter
+  }
+
+  emitter.apply = (opts = {}) => {
+    if (!emitter.updated) throw new Error('No update to apply')
+    if (opts.shouldFail) throw new Error('Mock applyUpdate failed')
+    emitter.applied = true
+    return Promise.resolve(emitter)
+  }
+
+  emitter.error = (error) => {
+    emitter.updating = false
+    emitter.updated = false
+    emitter.emit('error', error || new Error('Mock updater error'))
+    return Promise.resolve(emitter)
+  }
+
+  emitter.reset = () => {
+    emitter.nextVersion = null
+    emitter.updated = false
+    emitter.updating = false
+    emitter.applied = false
+    return emitter
+  }
+
+  return emitter
+}
+
+module.exports = { mock }

package/package.json

@@ -1 +1,49 @@
-{"name":"bare-tui-updater","version":"0.0.0"}
+{
+  "name": "bare-tui-updater",
+  "version": "0.0.1",
+  "description": "A drop-in 'update available' banner widget for bare-tui apps using pear-runtime's OTA updater",
+  "main": "index.js",
+  "exports": {
+    "./package": "./package.json",
+    ".": "./index.js",
+    "./pear": "./pear.js",
+    "./mock": "./mock.js",
+    "./theme": "./theme.js"
+  },
+  "files": [
+    "package.json",
+    "index.js",
+    "updater.js",
+    "theme.js",
+    "pear.js",
+    "mock.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "bare-tui": "^0.0.3"
+  },
+  "devDependencies": {
+    "bare-fs": "^4.7.1",
+    "bare-path": "^3.0.0",
+    "bare-stream": "^2.13.1",
+    "brittle": "^3.19.0",
+    "lunte": "^1.2.0",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "scripts": {
+    "format": "prettier --write . && lunte --fix",
+    "lint": "prettier --check . && lunte",
+    "test": "brittle-bare --coverage test/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holepunchto/bare-tui-updater.git"
+  },
+  "author": "Holepunch",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/holepunchto/bare-tui-updater/issues"
+  },
+  "homepage": "https://github.com/holepunchto/bare-tui-updater"
+}

package/pear.js

@@ -0,0 +1,30 @@
+function wire(widget, { updater, send }) {
+  if (typeof updater?.on !== 'function') {
+    throw new TypeError('bare-tui-updater/pear: updater must have an .on() method')
+  }
+  if (typeof send !== 'function') {
+    throw new TypeError('bare-tui-updater/pear: send must be a function')
+  }
+
+  const onUpdating = () => send({ type: 'update.downloading' })
+  const onDelta = (delta) => send({ type: 'update.progress', delta })
+  const onUpdated = () => send({ type: 'update.ready', version: updater.nextVersion })
+  const onError = (error) => send({ type: 'update.error', error })
+
+  updater.on('updating', onUpdating)
+  updater.on('updating-delta', onDelta)
+  updater.on('updated', onUpdated)
+  updater.on('error', onError)
+
+  if (updater.updated) onUpdated()
+  else if (updater.updating) onUpdating()
+
+  return function () {
+    updater.off('updating', onUpdating)
+    updater.off('updating-delta', onDelta)
+    updater.off('updated', onUpdated)
+    updater.off('error', onError)
+  }
+}
+
+module.exports = { wire }

package/theme.js

@@ -0,0 +1,15 @@
+const { style } = require('bare-tui')
+
+const defaultTheme = {
+  accent: (s) => style().foreground('cyan').render(s),
+  success: (s) => style().foreground('green').render(s),
+  error: (s) => style().foreground('red').render(s),
+  hint: (s) => style().faint(true).render(s),
+  border: style.borders.rounded
+}
+
+function merge(user) {
+  return { ...defaultTheme, ...(user || {}) }
+}
+
+module.exports = { defaultTheme, merge }

package/updater.js

@@ -0,0 +1,247 @@
+const { style } = require('bare-tui')
+const spinner = require('bare-tui').spinner
+const theme = require('./theme')
+
+let nextId = 1
+
+class Updater {
+  constructor(opts = {}) {
+    this.id = nextId++
+    this.tag = 0
+    this.width = opts.width || 60
+    this.themeOverrides = theme.merge(opts.theme)
+    this.onAccept = opts.onAccept || null
+    this.autoDismissMs = opts.autoDismissMs ?? 0
+    this.acceptKey = opts.acceptKey || 'u'
+    this.focused = opts.focused !== false
+    this.mode = opts.mode || 'confirm'
+    this.showProgress = opts.showProgress !== false
+    this.dismissible = opts.dismissible !== false
+    this.copy = { ...defaultCopy, ...(opts.copy || {}) }
+
+    this.state = 'idle'
+    this.version = null
+    this.error = null
+    this.progressCount = 0
+    this.progressBytesAdded = 0
+    this.spinner = spinner.create({ fps: 8 })
+
+    if (this.mode === 'silent' && this.onAccept) {
+      this._applyTimer = null
+    }
+  }
+
+  focus() {
+    this.focused = true
+    return this
+  }
+
+  blur() {
+    this.focused = false
+    return this
+  }
+
+  visible() {
+    return this.state !== 'idle'
+  }
+
+  update(msg) {
+    if (!msg) return [this, null]
+
+    switch (msg.type) {
+      case 'update.downloading':
+        if (this.state === 'applied' || this.state === 'applying') return [this, null]
+        this.state = 'downloading'
+        this.progressCount = 0
+        this.progressBytesAdded = 0
+        this.tag++
+        return [this, this.spinner.init()]
+
+      case 'update.progress':
+        if (this.state !== 'downloading') return [this, null]
+        if (msg.delta) {
+          this.progressCount++
+          if (msg.delta.bytesAdded) this.progressBytesAdded += msg.delta.bytesAdded
+        }
+        return [this, null]
+
+      case 'update.ready':
+        if (this.state === 'applied' || this.state === 'applying') return [this, null]
+        this.state = 'ready'
+        this.version = msg.version || this.version
+        this.tag++
+        if (this.mode === 'silent' && this.onAccept) {
+          return [this, this._acceptCmd()]
+        }
+        return [this, this._autoDismissCmd()]
+
+      case 'update.apply':
+        if (this.state !== 'ready') return [this, null]
+        this.state = 'applying'
+        this.tag++
+        return [this, this._acceptCmd()]
+
+      case 'update.applied':
+        if (msg.runId !== this.runId) return [this, null]
+        this.state = 'applied'
+        return [this, this._autoDismissCmd()]
+
+      case 'update.error':
+        if (this.state === 'applied') return [this, null]
+        this.state = 'error'
+        this.error = msg.error
+        this.tag++
+        return [this, this._autoDismissCmd()]
+
+      case 'update.dismiss':
+        if (!this.dismissible) return [this, null]
+        this.state = 'idle'
+        this.tag++
+        return [this, null]
+
+      case 'update.hide':
+        if (msg.id === this.id && msg.tag === this.tag) this.state = 'idle'
+        return [this, null]
+
+      case 'spinner.tick': {
+        if (this.state !== 'downloading' && this.state !== 'applying') return [this, null]
+        const [s, cmd] = this.spinner.update(msg)
+        this.spinner = s
+        return [this, cmd]
+      }
+
+      case 'key':
+        return this._onKey(msg)
+
+      default:
+        return [this, null]
+    }
+  }
+
+  _onKey(msg) {
+    if (!this.focused) return [this, null]
+
+    // Check if msg is a KeyMsg-like object or check the chord directly
+    const matches = (chord) => {
+      if (typeof msg.is === 'function') return msg.is(chord)
+      if (msg.chord === chord) return true
+      return false
+    }
+
+    if (this.state === 'ready' && (matches(this.acceptKey) || matches('enter'))) {
+      this.state = 'applying'
+      this.tag++
+      return [this, this._acceptCmd()]
+    }
+
+    if (
+      this.dismissible &&
+      (this.state === 'ready' || this.state === 'applied' || this.state === 'error') &&
+      matches('esc')
+    ) {
+      this.state = 'idle'
+      this.tag++
+      return [this, null]
+    }
+
+    return [this, null]
+  }
+
+  _acceptCmd() {
+    if (!this.onAccept) {
+      return () => ({ type: 'update.apply' })
+    }
+
+    const runId = (this.runId = {})
+    return () =>
+      Promise.resolve(this.onAccept())
+        .then(() => ({ type: 'update.applied', runId }))
+        .catch((error) => ({ type: 'update.error', error, runId }))
+  }
+
+  _autoDismissCmd() {
+    if (!this.autoDismissMs) return null
+    const id = this.id
+    const tag = ++this.tag
+    const ms = this.autoDismissMs
+    return () =>
+      new Promise((resolve) => setTimeout(() => resolve({ type: 'update.hide', id, tag }), ms))
+  }
+
+  view() {
+    const t = this.themeOverrides
+    let text
+
+    switch (this.state) {
+      case 'idle':
+      case 'disabled':
+        return ''
+
+      case 'downloading':
+        text =
+          (this.showProgress ? t.accent(this.spinner.view()) + ' ' : '') +
+          'Downloading update' +
+          (this.progressCount > 0
+            ? ` (${this.progressCount} file${this.progressCount === 1 ? '' : 's'})`
+            : '…')
+        break
+
+      case 'ready':
+        text =
+          t.success('✓') +
+          ' Update' +
+          (this.version ? ` v${this.version}` : '') +
+          ' ready — ' +
+          t.hint(`press ${this.acceptKey} to update, esc to dismiss`)
+        break
+
+      case 'applying':
+        text =
+          t.accent(this.spinner.view()) +
+          ' Applying update' +
+          (this.version ? ` v${this.version}` : '') +
+          '…'
+        break
+
+      case 'applied':
+        text =
+          t.success('✓') +
+          ' Updated' +
+          (this.version ? ` to v${this.version}` : '') +
+          ' — restart to use it'
+        break
+
+      case 'error':
+        text =
+          t.error('✗') +
+          ' Update failed' +
+          (this.error?.message ? `: ${this.error.message}` : this.error ? `: ${this.error}` : '')
+        break
+
+      default:
+        return ''
+    }
+
+    return style()
+      .border(t.border)
+      .borderForeground('cyan')
+      .padding(0, 1)
+      .width(Math.max(20, this.width))
+      .render(style.truncate(text, Math.max(20, this.width - 4)))
+  }
+}
+
+const defaultCopy = {
+  checking: 'Checking for updates…',
+  downloading: 'Downloading update',
+  ready: 'Update ready',
+  applying: 'Applying update',
+  applied: 'Updated',
+  error: 'Update failed'
+}
+
+function create(opts) {
+  return new Updater(opts)
+}
+
+module.exports = { create, Updater, defaultCopy }