swarmwire-cli 0.0.0-stage → 0.1.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,3 +1,50 @@
-# Temporary Holding Version
+# swarmwire-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+swarmwire send ./holiday-photos        # prints a link, keeps serving until you press ctrl-c
+swarmwire get "<link>"                 # on the other machine: downloads it, resumable
+```
+
+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]` | share a file or folder; prints a link |
+| `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) |
+
+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,318 @@
+#!/usr/bin/env node
+/**
+ * swarmwire send <path> [--private] [--bootstrap host:port]
+ * swarmwire get <link> [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 { 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
+
+Options:
+  --private           only people holding the link can find you (default: anyone who knows the hash can)
+  --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, 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 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)
+  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) throw new Error('get needs a link\n\n' + USAGE)
+
+  const parsed = parseLink(link)
+  const out = output ?? safeName(parsed.name) ?? parsed.root.slice(0, 16)
+
+  const swarm = createSwarm(flags)
+  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()
+}
+
+/** 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/package.json

@@ -1,6 +1,44 @@
 {
   "name": "swarmwire-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Send a file or folder to someone with a link. Peer to peer, from the terminal.",
+  "keywords": [
+    "cli",
+    "p2p",
+    "hyperswarm",
+    "file-transfer"
+  ],
+  "homepage": "https://github.com/tibocub/swarmwire-cli#readme",
+  "bugs": {
+    "url": "https://github.com/tibocub/swarmwire-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tibocub/swarmwire-cli.git"
+  },
+  "license": "MIT",
+  "author": "tibotibotibo",
+  "type": "module",
+  "bin": {
+    "swarmwire": "bin/swarmwire.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "brittle test/*.test.js"
+  },
+  "dependencies": {
+    "b4a": "^1.9.0",
+    "hyperdht": "^6.0.0",
+    "hyperswarm": "^4.17.2",
+    "swarmwire-lib": "^0.4.0"
+  },
+  "devDependencies": {
+    "@hyperswarm/testnet": "^3.1.4",
+    "brittle": "^3.19.1"
+  }
+}