swarmwire-cli 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tibotibotibotibotibotibotibotibotibotibotibo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,61 @@
-# Swarmwire-cli
+# swarmwire-cli
 
-placeholder for the swarmwire CLI repo.
+Send a file or a folder to someone with a link. Peer to peer, from the terminal: no account, no
+server, no upload. Built on [`swarmwire-lib`](https://github.com/tibocub/swarmwire).
 
+```
+npm i -g swarmwire-cli
 
-# Liscence
+swarmwire send ./holiday-photos        # prints a link, keeps serving until you press ctrl-c
+swarmwire get "<link>"                 # on the other machine: downloads it, resumable
+```
 
-MIT
+Generate QR codes for easy use with the [swarmwire android app](https://github.com/tibocub/swarmwire-mobile)
+```
+swarmwire send ./holiday-photos --qr   # also prints a QR code to flash from the android app
+swarmwire get --qr                     # displays a QR code that can be flashed to send a file from the android app
+```
+
+Anyone who knows what a file contains can find the people sharing it, whatever each calls it: two
+people sending the same file are one swarm. Pass `--private` to `send` for a link that carries a secret, so that only people
+holding the link can find you.
+
+Both commands keep a two-line status current. Receiving looks like this:
+
+```
+[=========>          ] 45% [2/3]  TOTAL: [154.2/344.0] MB
+UP: 1.1 MB/s  DOWN: 8.2 MB/s        Seeders: 1  Peers: 0
+```
+
+When the download is done the bar is replaced by `[Done] you are now seeding.` and `get` keeps
+running so others can fetch from you; ctrl-c stops it, `--exit` leaves as soon as it is done.
+Sending shows `[Seeding]` in place of the bar.
+
+*Seeders* are the peers connected to you that hold all of it, *Peers* the other ones. They are
+your direct connections only, never counting yourself and not the whole swarm. Someone who
+vanishes without saying goodbye (a pulled cable) drops off after the connection times out, about
+fifteen seconds. The speeds are bytes on the wire, so a little above the size of the data. Sizes
+are decimal: 1 MB is 1,000,000 bytes.
+
+## Options
+
+| | |
+|---|---|
+| `send <path> [--private] [--qr]` | share a file or folder; prints a link (`--qr`: also draws it as a QR code) |
+| `get --qr [output] [--exit]` | draw a QR code and wait: a phone scans it and hands over a link (its own file, or one forwarded from another device) |
+| `get <link> [output] [--exit]` | fetch by link, then keep seeding it (`--exit`: leave instead); the output defaults to the name in the link |
+| `--bootstrap host:port` | use a private DHT instead of the public one (for tests) |
+
+`get --qr` listens on a fresh one-shot key on the DHT, shown in the QR code and printed below it as
+`swarmwire-recv://<key>`. It takes the first valid link anyone sends it, then downloads as usual.
+The QR codes go to stderr, so `send`'s stdout is still just the link.
+
+Needs Node 20 or later. Files are shared where they lie: nothing is copied or written next to them.
+
+## Development
+
+```
+npm test        # real processes over a private DHT, no internet needed
+```
+
+MIT.

package/bin/swarmwire.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * swarmwire send <path> [--private] [--qr] [--bootstrap host:port]
+ * swarmwire get <link> [output] [--bootstrap host:port]
+ * swarmwire get --qr [output] [--bootstrap host:port]
+ *
+ * Deliberately two commands. Sending prints a link and keeps serving the file where it is;
+ * getting takes that link and nothing else.
+ */
+
+import { randomBytes } from 'crypto'
+import { stat } from 'fs/promises'
+import Hyperswarm from 'hyperswarm'
+import DHT from 'hyperdht'
+import b4a from 'b4a'
+import { renderQr } from '../lib/qr.js'
+import { receive } from '../lib/rendezvous.js'
+import { Swarmwire, parseLink, groupLength, DEFAULT_GROUP_LOG } from 'swarmwire-lib'
+
+const USAGE = `swarmwire - content-addressed file transfer, peer to peer
+
+  swarmwire send <path> [options]     share a file or folder; prints a link
+  swarmwire get <link> [output]       fetch a file or folder by link
+  swarmwire get --qr [output]         show a QR code; a phone scans it and hands over a link
+
+Options:
+  --private           only people holding the link can find you (default: anyone who knows the hash can)
+  --qr                send: also show the link as a QR code. get: wait for a link from a scanner
+  --exit              get: leave when the download is done instead of seeding it
+  --bootstrap <h:p>   use a private DHT instead of the public one
+  --help
+`
+
+// A terminal gets a two-line status rewritten in place. Anything else gets a line only when
+// who is connected changes: speeds and a bar would be a new line every half second.
+let shown = ''
+let drawn = false
+let lastPlain = ''
+
+const FLAGS = { private: false, exit: false, qr: false, help: false, bootstrap: true } // true: takes a value
+
+async function main () {
+  const { command, args, flags } = parseArgs(process.argv.slice(2))
+
+  if (flags.help || !command) return print(USAGE)
+  if (command === 'send') return send(args[0], flags)
+  if (command === 'get') return flags.qr ? get(null, args[0], flags) : get(args[0], args[1], flags)
+
+  throw new Error(`unknown command: ${command}\n\n${USAGE}`)
+}
+
+async function send (path, flags) {
+  if (!path) throw new Error('send needs a path\n\n' + USAGE)
+
+  const swarm = createSwarm(flags)
+  const node = new Swarmwire({ swarm })
+
+  // A private link carries its own secret, so only people holding it can find you.
+  const secret = flags.private ? randomBytes(32).toString('hex') : null
+  const folder = await isDirectory(path)
+
+  const { link, size, files } = folder
+    ? await node.serveCollection(path, { secret })
+    : await node.serve(path, { secret })
+
+  print(link)
+  if (flags.qr) warn(renderQr(link, { color: process.stderr.isTTY }))
+  warn(
+    folder
+      ? `serving ${path} (${files} files, ${bytes(size)})${flags.private ? ' privately' : ''}`
+      : `serving ${path} (${bytes(size)})${flags.private ? ' privately' : ''}`
+  )
+  warn('keep this running; ctrl-c to stop')
+
+  const poll = watch(node, swarm, link, () => '[Seeding]')
+
+  await interrupted()
+
+  clearInterval(poll)
+  warn('stopping')
+  await node.destroy()
+  await swarm.destroy()
+}
+
+async function get (link, output, flags) {
+  if (!link && !flags.qr) throw new Error('get needs a link\n\n' + USAGE)
+
+  const swarm = createSwarm(flags)
+
+  if (!link) {
+    link = await linkFromScanner(swarm)
+    if (!link) return swarm.destroy() // interrupted while waiting
+  }
+
+  const parsed = parseLink(link)
+  const out = output ?? safeName(parsed.name) ?? parsed.root.slice(0, 16)
+
+  const node = new Swarmwire({ swarm })
+
+  warn(`fetching ${parsed.root.slice(0, 16)}... into ${out}`)
+
+  // What the status line shows of the transfer: bytes of the whole thing, and which file.
+  const progress = { done: 0, total: parsed.size, file: 0, files: 0, finished: false }
+  let download = null
+
+  const poll = watch(node, swarm, parsed, () => {
+    if (progress.finished) return '[Done] you are now seeding.'
+    if (download) progress.done = Math.min(download.have * groupLength(DEFAULT_GROUP_LOG), parsed.size)
+
+    const counter = progress.files > 1 ? ` [${Math.min(progress.file + 1, progress.files)}/${progress.files}]` : ''
+    return `${bar(progress.done / progress.total)} ${Math.floor((progress.done / progress.total) * 100)}%${counter}  TOTAL: ${pair(progress.done, progress.total)}`
+  })
+
+  const work = (async () => {
+    if (parsed.type === 'collection') {
+      const list = await node.readList(parsed)
+      warn(`${list.files.length} files, ${bytes(list.size)}`)
+      progress.files = list.files.length
+
+      await node.downloadCollection(parsed, out, {
+        onfile: () => { progress.file++ },
+        onprogress: ({ bytes, total }) => Object.assign(progress, { done: bytes, total })
+      })
+
+    } else {
+      download = node.download(parsed, out)
+      await download
+    }
+  })()
+
+  const stopped = await Promise.race([work.then(() => false), interrupted().then(() => true)])
+
+  if (!stopped) {
+    progress.finished = true
+    if (!process.stderr.isTTY) warn(flags.exit ? '[Done]' : '[Done] you are now seeding.')
+    clearStatus() // the path goes below nothing: printed inside the status, the next redraw leaves its old bar behind
+    print(out)
+
+    if (!flags.exit) await interrupted()
+  }
+
+  clearInterval(poll)
+  warn('stopping')
+  await node.destroy()
+  await swarm.destroy()
+}
+
+/** Show a QR code for a one-shot meeting point and wait for a scanner to hand us a link. */
+async function linkFromScanner (swarm) {
+  const meeting = await receive(swarm.dht)
+
+  warn(renderQr(meeting.url, { color: process.stderr.isTTY }))
+  warn(`${meeting.url}\nscan this with the swarmwire app and pick something to send; ctrl-c to cancel`)
+
+  const link = await Promise.race([meeting.link, interrupted().then(() => null)])
+  await meeting.close()
+
+  return link
+}
+
+/** Resolves on ctrl-c or a polite kill, so serving can end cleanly. */
+function interrupted () {
+  return new Promise((resolve) => {
+    process.once('SIGINT', resolve)
+    process.once('SIGTERM', resolve)
+  })
+}
+
+/**
+ * Keep the status current: `lead()` is the first line, then speeds and who is connected.
+ * Peers are everyone connected who does not hold all of it; seeders are counted apart.
+ */
+function watch (node, swarm, link, lead) {
+  const meter = new Meter(swarm)
+
+  const show = () => {
+    const { peers, seeders } = node.counts(link)
+    const people = `Seeders: ${seeders}  Peers: ${peers - seeders}`
+    const { up, down } = meter.rates()
+
+    status(lead(), `UP: ${rate(up)}   DOWN: ${rate(down)}   ${people}`, people)
+  }
+
+  node.on('peer-connected', show)
+  node.on('peer-disconnected', show)
+  show()
+
+  return setInterval(show, 500) // a peer finishing, or progress, is not a connection event
+}
+
+/** Bytes on the wire in each direction, summed over every connection, past and present. */
+class Meter {
+  constructor (swarm) {
+    this.closed = { up: 0, down: 0 }
+    this.live = new Set()
+    this.samples = [] // recent { at, up, down }, for a rate smoothed over a couple of seconds
+
+    swarm.on('connection', (stream) => {
+      this.live.add(stream)
+      stream.once('close', () => {
+        this.live.delete(stream)
+        this.closed.up += stream.rawBytesWritten
+        this.closed.down += stream.rawBytesRead
+      })
+    })
+  }
+
+  rates () {
+    let { up, down } = this.closed
+    for (const stream of this.live) {
+      up += stream.rawBytesWritten
+      down += stream.rawBytesRead
+    }
+
+    const now = Date.now()
+    this.samples.push({ at: now, up, down })
+    while (this.samples.length > 5) this.samples.shift()
+
+    const first = this.samples[0]
+    const seconds = (now - first.at) / 1000
+    return seconds > 0 ? { up: (up - first.up) / seconds, down: (down - first.down) / seconds } : { up: 0, down: 0 }
+  }
+}
+
+function createSwarm ({ bootstrap }) {
+  if (!bootstrap) return new Hyperswarm()
+
+  const [host, port] = String(bootstrap).split(':')
+  const loopback = host === '127.0.0.1' || host === 'localhost'
+
+  const dht = new DHT({
+    bootstrap: [{ host, port: Number(port) }],
+    ephemeral: false,
+    firewalled: false,
+    // On a loopback DHT, bind there too: announcing a LAN address to peers that can only
+    // reach 127.0.0.1 leaves everyone findable and nobody connectable.
+    host: loopback ? '127.0.0.1' : undefined
+  })
+
+  return new Hyperswarm({ dht })
+}
+
+async function isDirectory (path) {
+  const info = await stat(path).catch(() => null)
+  if (info === null) throw new Error(`no such file or folder: ${path}`)
+
+  return info.isDirectory()
+}
+
+/** A filename hint is a hint: never let it climb out of the working directory. */
+function safeName (name) {
+  if (!name) return null
+
+  const base = name.split(/[\\/]/).pop()
+  return base && base !== '.' && base !== '..' ? base : null
+}
+
+function parseArgs (argv) {
+  const args = []
+  const flags = {}
+  let command = null
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+
+    if (!arg.startsWith('--')) {
+      if (command === null) command = arg
+      else args.push(arg)
+      continue
+    }
+
+    const [key, inline] = arg.slice(2).split('=')
+    if (!(key in FLAGS)) throw new Error(`unknown option: --${key}\n\n${USAGE}`)
+
+    flags[key] = FLAGS[key] ? (inline ?? argv[++i]) : true
+    if (flags[key] === undefined) throw new Error(`--${key} needs a value`)
+  }
+
+  return { command, args, flags }
+}
+
+const UNITS = ['B', 'KB', 'MB', 'GB', 'TB']
+
+/** The unit that keeps a size readable: 1 or more, below 1000. */
+function unitOf (n) {
+  return Math.min(Math.max(Math.floor(Math.log10(Math.max(n, 1)) / 3), 0), UNITS.length - 1)
+}
+
+function scaled (n, unit) {
+  return unit === 0 ? String(Math.round(n)) : (n / 1000 ** unit).toFixed(1)
+}
+
+function bytes (n) {
+  const unit = unitOf(n)
+  return `${scaled(n, unit)} ${UNITS[unit]}`
+}
+
+/** Progress in the unit of the total: "[254.0/344.0] MB". */
+function pair (done, total) {
+  const unit = unitOf(total)
+  return `[${scaled(done, unit)}/${scaled(total, unit)}] ${UNITS[unit]}`
+}
+
+function rate (perSecond) {
+  return `${bytes(perSecond)}/s`
+}
+
+function bar (fraction, width = 20) {
+  const filled = Math.min(width, Math.max(0, Math.floor(fraction * width)))
+  return '[' + '='.repeat(filled) + (filled < width ? '>' : '') + ' '.repeat(Math.max(0, width - filled - 1)) + ']'
+}
+
+function print (line) {
+  console.log(line)
+}
+
+function status (lead, detail, plain) {
+  const text = lead + '\n' + detail
+  if (text === shown) return
+  shown = text
+
+  if (!process.stderr.isTTY) return plain === lastPlain ? undefined : console.error((lastPlain = plain))
+
+  process.stderr.write((drawn ? '\x1b[2A' : '') + `\r\x1b[K${lead}\n\x1b[K${detail}\n`)
+  drawn = true
+}
+
+/** Erase the status so a line can be printed where it was; the next redraw starts below it. */
+function clearStatus () {
+  if (process.stderr.isTTY && drawn) process.stderr.write('\r\x1b[2A\x1b[J')
+  drawn = false
+  shown = ''
+}
+
+function warn (line) {
+  clearStatus()
+  console.error(line)
+}
+
+main().catch((err) => {
+  warn(String(err.message ?? err))
+  process.exit(1)
+})

package/lib/qr.js

@@ -0,0 +1,25 @@
+import { encode } from 'uqr'
+
+const QUIET = 2 // modules of white around the code, as the spec asks
+
+/**
+ * A QR code as terminal text, two modules per character row. Black on white is set
+ * explicitly when `color` is true: on a dark theme the default colors would invert the code.
+ */
+export function renderQr (text, { color = true } = {}) {
+  const { data, size } = encode(text, { ecc: 'L', border: 0 })
+  const dark = (x, y) => x >= 0 && y >= 0 && x < size && y < size && data[y][x]
+
+  const rows = []
+  for (let y = -QUIET; y < size + QUIET; y += 2) {
+    let row = ''
+    for (let x = -QUIET; x < size + QUIET; x++) {
+      const top = dark(x, y)
+      const bottom = dark(x, y + 1)
+      row += top && bottom ? '█' : top ? '▀' : bottom ? '▄' : ' '
+    }
+    rows.push(color ? `\x1b[30;47m${row}\x1b[0m` : row)
+  }
+
+  return rows.join('\n')
+}

package/lib/rendezvous.js

@@ -0,0 +1,88 @@
+/**
+ * A one-shot meeting point for handing a link to a machine that cannot be reached by one.
+ *
+ * `receive` listens on a fresh DHT keypair and shows its public key (as a QR code); whoever
+ * scans it calls `deliver` with a link, the listener checks it is one and answers. No topic,
+ * no discovery: the key is the address, and it is good for exactly one link.
+ */
+
+import b4a from 'b4a'
+import { parseLink } from 'swarmwire-lib'
+
+export const SCHEME = 'swarmwire-recv://'
+const MAX_LINK = 4096 // a link is ~150 bytes; this only bounds what a stranger can make us buffer
+
+/**
+ * @param {import('hyperdht')} dht
+ * @returns {Promise<{url: string, link: Promise<string>, close: () => Promise<void>}>}
+ */
+export async function receive (dht) {
+  const keyPair = dht.constructor.keyPair()
+  let resolve
+  const link = new Promise((r) => { resolve = r })
+  let done = false
+
+  const server = dht.createServer((socket) => {
+    let buffer = ''
+    socket.setEncoding('utf8')
+    socket.on('error', () => {}) // a scanner that walks away is not our problem
+    socket.on('data', (chunk) => {
+      buffer += chunk
+      if (buffer.length > MAX_LINK) return socket.destroy()
+
+      const end = buffer.indexOf('\n')
+      if (end < 0) return
+
+      const candidate = buffer.slice(0, end).trim()
+      buffer = ''
+
+      try {
+        if (done) throw new Error('already received')
+        parseLink(candidate)
+      } catch {
+        return socket.end('invalid\n')
+      }
+
+      done = true
+      socket.end('ok\n')
+      resolve(candidate)
+    })
+  })
+
+  await server.listen(keyPair)
+
+  return {
+    url: SCHEME + b4a.toString(keyPair.publicKey, 'hex'),
+    link,
+    close: () => server.close()
+  }
+}
+
+/**
+ * Hand `link` to the listener at `url`. Resolves once it has accepted it.
+ *
+ * @param {import('hyperdht')} dht
+ * @param {string} url
+ * @param {string} link
+ */
+export async function deliver (dht, url, link) {
+  if (!url.startsWith(SCHEME)) throw new Error(`not a swarmwire receive address: ${url}`)
+  const publicKey = b4a.from(url.slice(SCHEME.length), 'hex')
+  if (publicKey.length !== 32) throw new Error(`not a swarmwire receive address: ${url}`)
+
+  const socket = dht.connect(publicKey)
+  socket.setEncoding('utf8')
+
+  const answer = new Promise((resolve, reject) => {
+    let reply = ''
+    socket.on('data', (chunk) => { reply += chunk })
+    socket.on('error', reject)
+    socket.on('end', () => { socket.end(); resolve(reply.trim()) }) // the listener half-closes after its answer
+    socket.on('close', () => resolve(reply.trim()))
+  })
+
+  socket.write(link + '\n')
+  const reply = await answer
+
+  if (reply !== 'ok') throw new Error(`receiver refused the link${reply ? `: ${reply}` : ''}`)
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "swarmwire-cli",
-  "version": "0.0.1",
-  "description": "Easy P2P file transfer form the terminal",
+  "version": "0.2.0",
+  "description": "Send a file or folder to someone with a link. Peer to peer, from the terminal.",
   "keywords": [
     "cli",
     "p2p",
-    "hyperswarm"
+    "hyperswarm",
+    "file-transfer"
   ],
   "homepage": "https://github.com/tibocub/swarmwire-cli#readme",
   "bugs": {
@@ -18,8 +19,28 @@
   "license": "MIT",
   "author": "tibotibotibo",
   "type": "module",
-  "main": "index.js",
+  "bin": {
+    "swarmwire": "bin/swarmwire.js"
+  },
+  "files": [
+    "bin/",
+    "lib/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "brittle test/*.test.js"
+  },
+  "dependencies": {
+    "b4a": "^1.9.0",
+    "hyperdht": "^6.0.0",
+    "hyperswarm": "^4.17.2",
+    "swarmwire-lib": "^0.4.1",
+    "uqr": "^0.1.3"
+  },
+  "devDependencies": {
+    "@hyperswarm/testnet": "^3.1.4",
+    "brittle": "^3.19.1"
   }
 }