pear-install 0.0.0 → 1.0.2

package/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

package/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish
+on:
+  push:
+    tags:
+      - v*
+permissions:
+  id-token: write
+  contents: write
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+    name: Publish
+    steps:
+      - uses: holepunchto/actions/node-base@v1
+      - uses: holepunchto/actions/publish@v1

package/.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    name: Lint
+    steps:
+      - uses: holepunchto/actions/node-base@v1
+      - run: npm run lint
+
+  test:
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: linux
+          - os: macos-latest
+            platform: darwin
+          - os: windows-latest
+            platform: win32
+    runs-on: ${{ matrix.os }}
+    name: Test / ${{ matrix.platform }}
+    timeout-minutes: 2
+    steps:
+      - uses: holepunchto/actions/bare-base@v1
+      - run: npm test

package/.prettierignore

@@ -0,0 +1 @@
+template/appling/package.json

package/.prettierrc

@@ -0,0 +1 @@
+"prettier-config-holepunch"

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+   

package/NOTICE

@@ -0,0 +1,13 @@
+Copyright 2026 Holepunch Inc
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,15 @@
+# pear-install
+
+> Install Pear and Pear Applications
+
+# CLI
+
+```sh
+npx pear-install [link]
+```
+
+Install `pear` binary onto system, if a link is supplied, installs any Pear application or binary onto system.
+
+## License
+
+Apache-2.0

package/cmd.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+const pkg = require('./package.json')
+const { isWindows } = require('which-runtime')
+const { command, arg, bail } = require('paparam')
+const install = require('.')
+
+const program = command(
+  'install',
+  arg('[link]', 'Pear link origin to install from'),
+  async (cmd) => {
+    if (!cmd.args.link) cmd.args.link = pkg.pear.platform.key
+    await install(cmd)
+  },
+  pkg.command,
+  bail((info = {}) => {
+    process.exitCode = 1
+    let message
+    if (info.reason === 'UNKNOWN_FLAG') message = 'Unrecognized Flag: --' + info.flag.name
+    else if (info.reason === 'UNKNOWN_ARG') {
+      message = `Unrecognized Argument at index ${info.arg.index} with value ${info.arg.value}`
+    } else message = info.err?.message ?? 'Failed'
+    const cross = isWindows ? 'x' : '\x1B[31m✖\x1B[39m'
+    console.error(cross, message)
+    if (info.reason === 'UNKNOWN_FLAG' || info.reason === 'UNKNOWN_ARG') {
+      console.error('\n' + info.command.usage())
+    }
+  })
+)
+
+program.parse(process.argv.slice(2))

package/index.js

@@ -0,0 +1,343 @@
+'use strict'
+const path = require('path')
+const os = require('os')
+const fs = require('fs')
+const { spawnSync } = require('child_process')
+const process = require('process')
+const LocalDrive = require('localdrive')
+const { isMac, isLinux, isWindows } = require('which-runtime')
+const crypto = require('hypercore-crypto')
+const Corestore = require('corestore')
+const Hyperdrive = require('hyperdrive')
+const Hyperswarm = require('hyperswarm')
+const plink = require('pear-link')
+const Opstream = require('pear-opstream')
+const PearError = require('pear-errors')
+const byteSize = require('tiny-byte-size')
+const { ERR_INVALID_MANIFEST, ERR_NOT_FOUND, ERR_PERMISSION_REQUIRED, ERR_UNKNOWN } = PearError
+
+function ERR_NETWORK_TIMEOUT(msg, info = null) {
+  return new PearError(msg, ERR_NETWORK_TIMEOUT, info)
+}
+
+function ERR_EXISTS(msg, info = null) {
+  return new PearError(msg, ERR_EXISTS, info)
+}
+
+const PEAR_DIR = isMac
+  ? path.join(os.homedir(), 'Library', 'Application Support', 'pear')
+  : isLinux
+    ? path.join(os.homedir(), '.config', 'pear')
+    : path.join(os.homedir(), 'AppData', 'Roaming', 'pear')
+
+class Install extends Opstream {
+  static outputs = {
+    installing: ({ link }) => `Installing... ${link}`,
+    app: ({ app, version, upgrade, dest, key }) =>
+      `App: ${app}\nVersion: ${version}\nLink: ${upgrade}\nPathname: ${key}\nTarget: ${dest}`,
+    stats({ upload, download, peers }) {
+      const dl =
+        download.bytes + download.speed === 0
+          ? ''
+          : `[ down ${byteSize(download.bytes)} - ${byteSize(download.speed)}/s ] `
+      const ul =
+        upload.bytes + upload.speed === 0
+          ? ''
+          : `[ up ${byteSize(upload.bytes)} - ${byteSize(upload.speed)}/s ] `
+      return `[ Peers: ${peers} ] ${dl}${ul}`
+    },
+    error: ({ message }) => message,
+    final({ success, message }) {
+      if (success) return 'Installed'
+      return message ?? 'Failed'
+    }
+  }
+
+  constructor(params) {
+    super((...args) => this.#op(...args), params)
+    this.targets = []
+  }
+
+  async #op({ link, only, to, bootstrap, timeout = 30_000 }) {
+    const parsed = plink.parse(link)
+    if (parsed.pathname) throw new Error('Link must not have pathname')
+    const host = process.platform + '-' + process.arch
+    this.push({ tag: 'installing', data: { link, host } })
+
+    const rand = crypto.randomBytes(16).toString('hex')
+    const base = path.join(PEAR_DIR, 'gc', rand)
+    fs.mkdirSync(base, { recursive: true })
+
+    const corestore = new Corestore(base)
+    const drive = new Hyperdrive(corestore, parsed.drive.key)
+    const swarm = new Hyperswarm({ bootstrap })
+
+    let findingDone = null
+    try {
+      await drive.ready()
+      findingDone = drive.findingPeers()
+      const topic = swarm.join(drive.discoveryKey, { server: false, client: true })
+      swarm.on('connection', (c) => corestore.replicate(c))
+
+      let serving = false
+      swarm.dht.on('nat-update', () => {
+        if (!swarm.dht.randomized && !serving) {
+          serving = true
+          swarm
+            .join(drive.discoveryKey, { server: true, client: false })
+            .flushed()
+            .then(() => topic.destroy())
+        }
+      })
+      const deferred = Promise.withResolvers()
+      const countdown = setTimeout(() => {
+        deferred.reject(ERR_NETWORK_TIMEOUT('Network Timeout ' + timeout / 1000 + 's'))
+      }, timeout)
+      await Promise.race([drive.core.update({ wait: true }), deferred.promise])
+      clearTimeout(countdown)
+      const pkg = await drive.get('/package.json')
+      if (pkg === null) throw ERR_INVALID_MANIFEST('Unable to read application package.json')
+      const manifest = JSON.parse(pkg.toString())
+
+      const { name, productName, version, upgrade, bin } = manifest
+      const appName = productName ?? name
+      const home = os.homedir()
+
+      if (bin) {
+        const bins = typeof bin === 'string' ? { [name]: bin } : bin
+        for (const binName of Object.keys(bins)) {
+          const ext = isWindows ? '.msix' : ''
+          const dest = isWindows
+            ? null
+            : to
+              ? path.join(to, binName + ext)
+              : isMac
+                ? path.join('/', 'usr', 'local', 'bin', binName)
+                : path.join(home, '.local', 'bin', binName)
+          this.targets.push({ filename: binName, ext, dest, isBin: true })
+        }
+      }
+
+      const ext = isMac ? '.app' : isWindows ? '.msix' : '.AppImage'
+      const dest = isWindows
+        ? null
+        : to
+          ? path.join(to, appName + ext)
+          : isMac
+            ? path.join('/', 'Applications', appName + ext)
+            : fs.existsSync(path.join(home, 'Applications'))
+              ? path.join(home, 'Applications', appName + ext)
+              : fs.existsSync(path.join(home, 'AppImages'))
+                ? path.join(home, 'AppImages', appName + ext)
+                : path.join(home, '.local', 'bin', appName + ext)
+
+      this.targets.push({ filename: appName, ext, dest, isBin: false })
+
+      const present = new Set()
+      const appPath = '/by-arch/' + host + '/app/'
+      for await (const name of drive.readdir(appPath)) present.add(name)
+
+      const required = only
+        ? only
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean)
+        : this.targets.filter((t) => t.isBin || !bin).map((t) => t.filename + t.ext)
+      const missing = required
+        .filter((r) => !present.has(r))
+        .map((name) => plink.serialize({ ...parsed, pathname: appPath + name }))
+      if (missing.length) {
+        throw ERR_NOT_FOUND('Not found: ' + missing.join(', '))
+      }
+
+      this.targets = this.targets.filter(({ filename, ext }) => present.has(filename + ext))
+
+      const exists = []
+      const installs = []
+      for (const target of this.targets) {
+        if (isWindows) {
+          const ps = spawnSync('powershell', [
+            '-NoProfile',
+            '-Command',
+            `(Get-AppxPackage '${target.filename}') -ne $null`
+          ])
+          if (ps.stdout.toString().trim() === 'True') {
+            exists.push({ filename: target.filename, dest: target.dest })
+            continue
+          }
+        } else if (fs.existsSync(target.dest)) {
+          exists.push({ filename: target.filename, dest: target.dest })
+          continue
+        }
+        installs.push(target)
+      }
+
+      if (installs.length === 0) {
+        const message = isWindows
+          ? `Already installed:\n${exists.map(({ filename }) => '  ' + filename).join('\n')}\n  Manually uninstall first to reinstall`
+          : `Refusing to overwrite existing:\n${exists.map(({ dest }) => '  ' + dest).join('\n')}\n  Manually remove first to reinstall`
+        throw ERR_EXISTS(message)
+      }
+
+      const tmp = path.join(base, 'targets')
+      fs.mkdirSync(tmp, { recursive: true })
+      const prefixes = installs.map(({ filename, ext }) => appPath + filename + ext)
+      const mirror = drive.mirror(new LocalDrive(tmp), {
+        prefix: prefixes,
+        prune: false,
+        progress: true,
+        dedup: true
+      })
+      const monitor = mirror.monitor()
+      monitor.on('update', (stats) => this.push({ tag: 'stats', data: stats }))
+      await mirror.done()
+      monitor.destroy()
+
+      let installed = 0
+      for (const { filename, ext, dest, isBin } of installs) {
+        const key = appPath + filename + ext
+        this.push({ tag: 'app', data: { app: filename, name, version, upgrade, key, tmp, dest } })
+
+        const from = path.join(tmp, 'by-arch', host, 'app', filename + ext)
+
+        if (fs.existsSync(from) === false) {
+          throw ERR_NOT_FOUND(plink.serialize({ ...parsed, pathname: key }))
+        }
+
+        if (isWindows) {
+          const MSIXManager = require('msix-manager')
+          await new MSIXManager().addPackage(from)
+          installed++
+          continue
+        }
+
+        if (isBin) {
+          try {
+            if (!to) fs.mkdirSync(path.dirname(dest), { recursive: true })
+            this._move(from, dest)
+          } catch (err) {
+            if (err.code === 'EACCES' || err.code === 'EPERM') {
+              const dir = path.dirname(dest)
+              const fix = isMac
+                ? `sudo chgrp admin ${dir} && sudo chmod g+w ${dir}`
+                : `sudo chown -R "$(id -un):$(id -gn)" ${dir}`
+              throw ERR_PERMISSION_REQUIRED(`Permission denied: ${dest}\n  Fix: ${fix}`)
+            }
+            throw err
+          }
+          fs.chmodSync(dest, 0o755)
+        } else {
+          try {
+            await fs.promises.rename(from, dest)
+          } catch (err) {
+            if (err.code === 'EACCES' || err.code === 'EPERM') {
+              const dir = path.dirname(dest)
+              const fix = isMac
+                ? `sudo chgrp admin ${dir} && sudo chmod g+w ${dir}`
+                : `sudo chown -R "$(id -un):$(id -gn)" ${dir}`
+              throw ERR_PERMISSION_REQUIRED(`Permission denied: ${dest}\n  Fix: ${fix}`)
+            }
+            throw err
+          }
+          if (isLinux) await this._linux(dest, filename, tmp, home)
+        }
+        installed++
+      }
+      if (installed === 0) {
+        throw ERR_UNKNOWN('Failed to install')
+      }
+      this.final = { success: true, installed, exists }
+    } finally {
+      if (findingDone) findingDone()
+      await drive.close()
+      await swarm.destroy()
+      await corestore.close()
+      fs.rmSync(base, { recursive: true, force: true })
+    }
+  }
+
+  static async output(json, stream) {
+    for await (const { tag, data } of stream) {
+      if (json) {
+        process.stdout.write(JSON.stringify({ cmd: 'install', tag, data }) + '\n')
+        continue
+      }
+      if (tag === 'final') {
+        process.stdout.write('\r\x1B[2K' + this.outputs.final(data) + '\n')
+        return data
+      } else if (this.outputs[tag]) {
+        process.stdout.write('\r\x1B[2K' + this.outputs[tag](data) + '\n')
+      }
+    }
+  }
+
+  async _linux(dest, appName, tmp, home) {
+    fs.chmodSync(dest, 0o755)
+    const extracted = path.join(tmp, 'squashfs-root')
+    const desktopPath = this._extract(dest, extracted, tmp, appName + '.desktop')
+    const desktop = fs.readFileSync(desktopPath, 'utf8').replace(/^Exec=.*/m, `Exec=${dest}`)
+    fs.writeFileSync(desktopPath, desktop)
+
+    spawnSync(dest, ['--appimage-extract', 'usr/share/icons'], { cwd: tmp })
+    const src = new LocalDrive(path.join(extracted, 'usr', 'share', 'icons', 'hicolor'), {
+      followLinks: true
+    })
+    const dst = new LocalDrive(path.join(home, '.local', 'share', 'icons', 'hicolor'))
+    const mirror = src.mirror(dst, { prune: false })
+    await mirror.done()
+
+    this._move(
+      desktopPath,
+      path.join(home, '.local', 'share', 'applications', appName + '.desktop')
+    )
+  }
+
+  _extract(appImage, extracted, cwd, file) {
+    const { status } = spawnSync(appImage, ['--appimage-extract', file], { cwd })
+    if (status !== 0) throw new Error('appimage-extract failed')
+    const full = path.join(extracted, file)
+    let stat = null
+    try {
+      stat = fs.lstatSync(full)
+    } catch {}
+    if (stat !== null && !stat.isSymbolicLink()) return full
+    const link = fs.readlinkSync(full)
+    const target = path.resolve(path.dirname(full), link)
+    let exists = true
+    try {
+      fs.lstatSync(target)
+    } catch {
+      exists = false
+    }
+    return exists
+      ? target
+      : this._extract(appImage, extracted, cwd, path.relative(extracted, target))
+  }
+
+  _move(src, dst) {
+    try {
+      fs.renameSync(src, dst)
+    } catch (err) {
+      if (err.code === 'ENOENT') return // ignore if path does not exist
+      if (err.code !== 'EXDEV') throw err
+      fs.copyFileSync(src, dst)
+      fs.rmSync(src)
+    }
+  }
+}
+
+module.exports = async function (cmd) {
+  const { json, only, to, dhtBootstrap } = cmd.flags
+  const timeout = (cmd.flags.timeout || 30) * 1000
+  const link = cmd.args.link
+  const bootstrap = dhtBootstrap
+    ? dhtBootstrap.split(',').map((tuple) => {
+        const [host, port] = tuple.split(':')
+        const int = +port
+        if (Number.isInteger(int) === false) throw new Error(`Invalid port: ${port}`)
+        return { host, port: int }
+      })
+    : undefined
+  const stream = new Install({ link, only, to, bootstrap, timeout })
+  await Install.output(json, stream)
+}

package/package.json

@@ -1 +1,94 @@
-{"name":"pear-install","version":"0.0.0"}
+{
+  "name": "pear-install",
+  "version": "1.0.2",
+  "main": "index.js",
+  "type": "commonjs",
+  "description": "Install Pear and Pear Applications",
+  "author": "Holepunch Inc",
+  "license": "Apache-2.0",
+  "bin": {
+    "pear-install": "cmd.js"
+  },
+  "imports": {
+    "process": {
+      "bare": "bare-process",
+      "default": "process"
+    },
+    "child_process": {
+      "bare": "bare-subprocess",
+      "default": "child_process"
+    },
+    "fs": {
+      "bare": "bare-fs",
+      "default": "fs"
+    },
+    "os": {
+      "bare": "bare-os",
+      "default": "os"
+    },
+    "path": {
+      "bare": "bare-path",
+      "default": "path"
+    }
+  },
+  "scripts": {
+    "format": "prettier --write . && lunte --fix .",
+    "lint": "prettier --check . && lunte",
+    "test:gen": "brittle -r test/all.js test/*.test.js",
+    "test": "npm run test:node && npm run test:bare",
+    "test:node": "brittle-node --coverage test/all.js",
+    "test:bare": "brittle-bare --coverage test/all.js"
+  },
+  "command": {
+    "summary": "Install applications from peers",
+    "description": "Installs from peers directly into OS application folder",
+    "flag --only <paths>": "Advanced. Filter by app filenames",
+    "flag --timeout seconds": "Advanced. Override network timeout (30s)",
+    "flag --to <dir>": "Advanced. Override install target directory",
+    "flag --dht-bootstrap <nodes>": "Advanced. Custom DHT bootstrap",
+    "flag --json": "Newline delimited JSON output"
+  },
+  "pear": {
+    "platform": {
+      "key": "pear://pzcjqmpoo6szkoc4bpkw65ib9ctnrq7b6mneeinbhbheihaq6p6o"
+    }
+  },
+  "dependencies": {
+    "bare-fs": "^4.7.1",
+    "bare-os": "^3.9.1",
+    "bare-path": "^3.0.0",
+    "bare-process": "^4.4.1",
+    "bare-subprocess": "^6.0.0",
+    "corestore": "^7.9.2",
+    "hypercore-crypto": "^3.7.0",
+    "hyperdrive": "^13.3.2",
+    "hyperswarm": "^4.17.0",
+    "localdrive": "^2.2.1",
+    "pear-errors": "^1.0.1",
+    "pear-link": "^4.2.1",
+    "pear-opstream": "^1.0.1",
+    "pear-opwait": "^1.0.0",
+    "streamx": "^2.23.0",
+    "tiny-byte-size": "^1.1.0"
+  },
+  "devDependencies": {
+    "brittle": "^3.19.1",
+    "lunte": "^1.8.0",
+    "prettier": "^3.7.4",
+    "prettier-config-holepunch": "^2.0.0",
+    "test-tmp": "^1.4.0",
+    "which-runtime": "^1.3.2"
+  },
+  "directories": {
+    "test": "test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holepunchto/pear-install.git"
+  },
+  "keywords": [],
+  "bugs": {
+    "url": "https://github.com/holepunchto/pear-install/issues"
+  },
+  "homepage": "https://github.com/holepunchto/pear-install#readme"
+}

package/test/all.js

@@ -0,0 +1,13 @@
+// This runner is auto-generated by Brittle
+
+runTests()
+
+async function runTests() {
+  const test = (await import('brittle')).default
+
+  test.pause()
+
+  await import('./index.test.js')
+
+  test.resume()
+}

package/test/helper.js

@@ -0,0 +1,80 @@
+'use strict'
+const Corestore = require('corestore')
+const Hyperdrive = require('hyperdrive')
+const Hyperswarm = require('hyperswarm')
+const tmp = require('test-tmp')
+const { command, arg, bail } = require('paparam')
+const pkg = require('../package.json')
+const install = require('..')
+const process = require('process')
+const arch = `${process.platform}-${process.arch}`
+
+async function seed(t, { bootstrap, manifest, files }) {
+  const storage = await tmp(t)
+  const corestore = new Corestore(storage)
+  const drive = new Hyperdrive(corestore)
+  await drive.ready()
+  await drive.put('/package.json', Buffer.from(JSON.stringify(manifest)))
+  for (const [p, content] of Object.entries(files)) {
+    await drive.put(p, Buffer.from(content))
+  }
+  const swarm = new Hyperswarm({ bootstrap })
+  swarm.on('connection', (c) => corestore.replicate(c))
+  swarm.join(drive.discoveryKey, { server: true, client: false })
+  await swarm.flush()
+  t.teardown(async () => {
+    await swarm.destroy()
+    await drive.close()
+    await corestore.close()
+  })
+  return drive.key
+}
+
+async function run(args) {
+  const lines = []
+  let buf = ''
+  const origWrite = process.stdout.write
+  const origExitCode = process.exitCode
+  process.stdout.write = function (chunk) {
+    buf += chunk.toString()
+    let i
+    while ((i = buf.indexOf('\n')) !== -1) {
+      lines.push(buf.slice(0, i))
+      buf = buf.slice(i + 1)
+    }
+    return true
+  }
+  let bailInfo = null
+  let exitCode
+  try {
+    const program = command(
+      'install',
+      arg('[link]', 'Pear link'),
+      pkg.command,
+      install,
+      bail((info) => {
+        bailInfo = info
+      })
+    )
+    const c = program.parse(args, { run: true })
+    if (c?.running) await c.running.catch(() => {})
+  } finally {
+    process.stdout.write = origWrite
+    exitCode = process.exitCode
+    process.exitCode = origExitCode
+  }
+  const events = lines.flatMap((l) => {
+    try {
+      return [JSON.parse(l)]
+    } catch {
+      return []
+    }
+  })
+  return { events, bail: bailInfo, stdout: lines.join('\n') + buf, exitCode }
+}
+
+function bootstrapArg(testnet) {
+  return testnet.bootstrap.map((b) => `${b.host}:${b.port}`).join(',')
+}
+
+module.exports = { seed, run, arch, bootstrapArg }

package/test/index.test.js

@@ -0,0 +1,238 @@
+'use strict'
+const test = require('brittle')
+const path = require('path')
+const fs = require('fs')
+const createTestnet = require('hyperdht/testnet')
+const hypercoreCrypto = require('hypercore-crypto')
+const hid = require('hypercore-id-encoding')
+const plink = require('pear-link')
+const { isWindows } = require('which-runtime')
+const tmp = require('test-tmp')
+const { seed, run, arch, bootstrapArg } = require('./helper')
+
+test('successful bin install via testnet', { skip: isWindows }, async function (t) {
+  t.timeout(60000)
+  const testnet = await createTestnet(3, t.teardown)
+  const key = await seed(t, {
+    bootstrap: testnet.bootstrap,
+    manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+    files: { ['/by-arch/' + arch + '/app/tbin']: 'BIN' }
+  })
+  const link = plink.serialize({ drive: { key } })
+  const target = await tmp(t)
+  const { events } = await run([
+    '--json',
+    '--to',
+    target,
+    '--dht-bootstrap',
+    bootstrapArg(testnet),
+    link
+  ])
+  const final = events.find((e) => e.tag === 'final')
+  t.ok(final, 'final event emitted')
+  t.is(final.data.success, true, 'success')
+  t.is(fs.readFileSync(path.join(target, 'tbin'), 'utf8'), 'BIN', 'bin written to target')
+})
+
+test('notFound emits full pear:// link when platform binary missing', async function (t) {
+  t.timeout(60000)
+  const testnet = await createTestnet(3, t.teardown)
+  const key = await seed(t, {
+    bootstrap: testnet.bootstrap,
+    manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+    files: {}
+  })
+  const link = plink.serialize({ drive: { key } })
+  const target = await tmp(t)
+  const { events } = await run([
+    '--json',
+    '--to',
+    target,
+    '--dht-bootstrap',
+    bootstrapArg(testnet),
+    link
+  ])
+  const final = events.find((e) => e.tag === 'final')
+  const error = events.find((e) => e.tag === 'error')
+  t.ok(final, 'final event emitted')
+  t.is(final.data.success, false, 'failure')
+  t.is(error?.data.code, 'ERR_NOT_FOUND', 'ERR_NOT_FOUND emitted')
+  t.ok(error?.data.message.includes('pear://'), 'error message includes pear link')
+  t.ok(
+    error?.data.message.includes('/by-arch/' + arch + '/app/tbin'),
+    'error message includes platform path'
+  )
+})
+
+test('refuses to overwrite an existing install', { skip: isWindows }, async function (t) {
+  t.timeout(60000)
+  const testnet = await createTestnet(3, t.teardown)
+  const key = await seed(t, {
+    bootstrap: testnet.bootstrap,
+    manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+    files: { ['/by-arch/' + arch + '/app/tbin']: 'NEW' }
+  })
+  const link = plink.serialize({ drive: { key } })
+  const target = await tmp(t)
+  fs.writeFileSync(path.join(target, 'tbin'), 'EXISTING')
+  const { events } = await run([
+    '--json',
+    '--to',
+    target,
+    '--dht-bootstrap',
+    bootstrapArg(testnet),
+    link
+  ])
+  const final = events.find((e) => e.tag === 'final')
+  const error = events.find((e) => e.tag === 'error')
+  t.ok(final, 'final event emitted')
+  t.is(final.data.success, false, 'failure')
+  t.is(error?.data.code, 'ERR_EXISTS', 'ERR_EXISTS emitted')
+  t.ok(
+    error?.data.message.includes('Refusing to overwrite existing'),
+    'error message reports refusal'
+  )
+  t.ok(
+    error?.data.message.includes(path.join(target, 'tbin')),
+    'error message lists existing target path'
+  )
+  t.is(fs.readFileSync(path.join(target, 'tbin'), 'utf8'), 'EXISTING', 'existing file untouched')
+})
+
+test('invalid port in --dht-bootstrap reaches bail handler', async function (t) {
+  const { bail: info } = await run([
+    '--dht-bootstrap',
+    '127.0.0.1:nope',
+    'pear://aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
+  ])
+  t.ok(info, 'bail handler invoked')
+  t.is(info.err?.message, 'Invalid port: nope')
+})
+
+test('link with pathname emits error event', async function (t) {
+  const key = hid.encode(hypercoreCrypto.keyPair().publicKey)
+  const link = `pear://${key}/some/path`
+  const { events } = await run(['--json', link])
+  const error = events.find((e) => e.tag === 'error')
+  t.ok(error, 'error event emitted')
+  t.is(error.data.message, 'Link must not have pathname')
+})
+
+test(
+  'non-json output prints installing, app and Installed',
+  { skip: isWindows },
+  async function (t) {
+    t.timeout(60000)
+    const testnet = await createTestnet(3, t.teardown)
+    const key = await seed(t, {
+      bootstrap: testnet.bootstrap,
+      manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+      files: { ['/by-arch/' + arch + '/app/tbin']: 'BIN' }
+    })
+    const link = plink.serialize({ drive: { key } })
+    const target = await tmp(t)
+    const { stdout } = await run(['--to', target, '--dht-bootstrap', bootstrapArg(testnet), link])
+    t.ok(stdout.includes('Installing...'), 'installing message printed')
+    t.ok(stdout.includes('App: tbin'), 'app message printed')
+    t.ok(stdout.includes('Installed'), 'final installed message printed')
+  }
+)
+
+test(
+  'non-json output prints Not found for missing platform binary',
+  { skip: isWindows },
+  async function (t) {
+    t.timeout(60000)
+    const testnet = await createTestnet(3, t.teardown)
+    const key = await seed(t, {
+      bootstrap: testnet.bootstrap,
+      manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+      files: {}
+    })
+    const link = plink.serialize({ drive: { key } })
+    const target = await tmp(t)
+    const { stdout } = await run(['--to', target, '--dht-bootstrap', bootstrapArg(testnet), link])
+    t.ok(stdout.includes('Not found: pear://'), 'not found message printed')
+  }
+)
+
+test(
+  'non-json output prints Refusing to overwrite for existing target',
+  { skip: isWindows },
+  async function (t) {
+    t.timeout(60000)
+    const testnet = await createTestnet(3, t.teardown)
+    const key = await seed(t, {
+      bootstrap: testnet.bootstrap,
+      manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+      files: { ['/by-arch/' + arch + '/app/tbin']: 'BIN' }
+    })
+    const link = plink.serialize({ drive: { key } })
+    const target = await tmp(t)
+    fs.writeFileSync(path.join(target, 'tbin'), 'EXISTING')
+    const { stdout } = await run(['--to', target, '--dht-bootstrap', bootstrapArg(testnet), link])
+    t.ok(stdout.includes('Refusing to overwrite existing'), 'refusing message printed')
+    t.ok(stdout.includes('Manually remove first'), 'fix hint printed')
+  }
+)
+
+test('_move falls back to copy+rm on EXDEV', { skip: isWindows }, async function (t) {
+  t.timeout(60000)
+  const testnet = await createTestnet(3, t.teardown)
+  const key = await seed(t, {
+    bootstrap: testnet.bootstrap,
+    manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+    files: { ['/by-arch/' + arch + '/app/tbin']: 'BIN' }
+  })
+  const link = plink.serialize({ drive: { key } })
+  const target = await tmp(t)
+  const renameSync = fs.renameSync
+  fs.renameSync = function () {
+    const err = new Error('cross-device link not permitted')
+    err.code = 'EXDEV'
+    throw err
+  }
+  t.teardown(() => {
+    fs.renameSync = renameSync
+  })
+  const { events } = await run([
+    '--json',
+    '--to',
+    target,
+    '--dht-bootstrap',
+    bootstrapArg(testnet),
+    link
+  ])
+  const final = events.find((e) => e.tag === 'final')
+  t.is(final?.data?.success, true, 'install succeeded via copy+rm fallback')
+  t.is(fs.readFileSync(path.join(target, 'tbin'), 'utf8'), 'BIN', 'bin content copied to target')
+})
+
+test('permission denied when target dir is read-only', { skip: isWindows }, async function (t) {
+  t.timeout(60000)
+  const testnet = await createTestnet(3, t.teardown)
+  const key = await seed(t, {
+    bootstrap: testnet.bootstrap,
+    manifest: { name: 'tbin', version: '1.0.0', upgrade: 'pear://x', bin: 'cli.js' },
+    files: { ['/by-arch/' + arch + '/app/tbin']: 'BIN' }
+  })
+  const link = plink.serialize({ drive: { key } })
+  const target = await tmp(t)
+  fs.chmodSync(target, 0o555)
+  t.teardown(() => {
+    try {
+      fs.chmodSync(target, 0o755)
+    } catch {}
+  })
+  const { events, stdout } = await run([
+    '--to',
+    target,
+    '--dht-bootstrap',
+    bootstrapArg(testnet),
+    link
+  ])
+  // since no --json, events is empty; assert via stdout
+  t.is(events.length, 0, 'no json events (non-json mode)')
+  t.ok(stdout.includes('Permission denied'), 'permission message printed')
+  t.ok(stdout.includes('Fix:'), 'fix hint printed')
+})