gnutella 1.0.0

package/QUICKSTART.md

@@ -0,0 +1,133 @@
+# Quickstart
+
+This guide gets you from zero to a working CLI session with sharing, searching, browsing, and downloading.
+
+## 1. Get GnutellaBun
+
+You can either:
+
+- download a prebuilt binary from the [releases page](https://github.com/RickCarlino/gnutella-bun-client/releases)
+- run from source with Bun
+
+If you are running from source:
+
+```bash
+bun install
+```
+
+Throughout this guide, commands use the CLI command:
+
+```bash
+gnutella
+```
+
+If you are running from source, replace `gnutella` with:
+
+```bash
+bun run bin/gnutella.ts
+```
+
+If you are using a compiled binary, replace `gnutella` with the executable path.
+
+## 2. Create A Config
+
+```bash
+gnutella init --config gnutella.json
+```
+
+This creates a config file and a downloads folder.
+
+By default, GnutellaBun shares files from `./downloads` and also saves downloaded files there.
+
+## 3. Put Files In Your Share Folder
+
+Copy any files you want to share into `./downloads`.
+
+If you changed `config.data_dir`, use `<data_dir>/downloads` instead.
+
+## 4. Start The Client
+
+```bash
+gnutella run --config gnutella.json
+```
+
+GnutellaBun will try to bootstrap on its own. If you already know a peer and want to connect to it directly, you can still use `connect <ip:port>` after startup.
+
+Useful first commands:
+
+```text
+status
+peers
+shares
+```
+
+## 5. Search For Files
+
+```text
+query hello world
+results
+info 1
+```
+
+`results` gives you numbered hits.
+
+`info 1` shows the details for result `1`.
+
+If you want a magnet link for a result:
+
+```text
+magnet 1
+```
+
+## 6. Browse A Host
+
+If a peer looks interesting, you can browse its whole shared library.
+
+First list your connected peers:
+
+```text
+peers
+```
+
+Then browse by peer key:
+
+```text
+browse p1
+```
+
+You can also browse directly by address:
+
+```text
+browse 203.0.113.10:6346
+```
+
+## 7. Download A Result
+
+Download to the default folder:
+
+```text
+download 1
+```
+
+Or pick an explicit destination:
+
+```text
+download 1 ./my-copy.bin
+```
+
+If the destination file already exists, GnutellaBun resumes from the current file size when possible.
+
+## 8. Save And Quit
+
+```text
+save
+quit
+```
+
+`save` writes the current config and remembered peers to disk right away.
+
+## If Something Looks Empty
+
+- No peers yet: give bootstrap a little time, or run `connect <ip:port>` if you already know a live peer.
+- No results yet: wait a few seconds after connecting, then try another query.
+- Want the full command list and config reference: read [CLI.md](CLI.md).

package/README.md

@@ -0,0 +1,74 @@
+# GnutellaBun
+
+GnutellaBun is a small Bun-based Gnutella client you can run from the terminal or embed in a TypeScript app.
+
+It is built for people who want to:
+
+- share files from one folder
+- search the Gnutella network
+- inspect results before downloading
+- browse another peer's shared library
+- keep useful state across restarts
+
+It can be used in three ways:
+
+- as an interactive CLI
+- as a scripted CLI runner
+- as a library inside another app
+
+It interoperates with other Gnutella clients, including GTK Gnutella.
+
+## Prebuilt Binaries
+
+- [Windows](https://github.com/RickCarlino/gnutella-bun-client/releases/latest/download/gnutella-bun-windows-x64.exe)
+- [Windows (older CPUs)](https://github.com/RickCarlino/gnutella-bun-client/releases/latest/download/gnutella-bun-windows-x64-baseline.exe)
+- [macOS Intel](https://github.com/RickCarlino/gnutella-bun-client/releases/latest/download/gnutella-bun-darwin-x64)
+- [macOS Apple Silicon](https://github.com/RickCarlino/gnutella-bun-client/releases/latest/download/gnutella-bun-darwin-arm64)
+- [Linux builds](https://github.com/RickCarlino/gnutella-bun-client/releases)
+- [All releases](https://github.com/RickCarlino/gnutella-bun-client/releases)
+
+Download a prebuilt executable from the [releases page](https://github.com/RickCarlino/gnutella-bun-client/releases).
+
+After downloading, run the executable directly:
+
+```bash
+./gnutella-bun-linux-x64 init --config gnutella.json
+./gnutella-bun-linux-x64 run --config gnutella.json
+```
+
+## From Source
+
+If you want to run from source:
+
+```bash
+bun install
+bun run bin/gnutella.ts init --config gnutella.json
+bun run bin/gnutella.ts run --config gnutella.json
+```
+
+## Library Use
+
+**NOTE:** Node support is not done. Use Bun.
+
+When used from this repository, the public TypeScript import is:
+
+```ts
+import { GnutellaServent, loadDoc } from "gnutella";
+
+const configPath = "./gnutella.json";
+const doc = await loadDoc(configPath);
+const node = new GnutellaServent(configPath, doc);
+
+await node.start();
+node.sendQuery("hello world");
+```
+
+## Guides
+
+- [Quickstart](QUICKSTART.md): get the CLI working in a few minutes
+- [CLI Guide](CLI.md): full command and config reference
+- [Developer Guide](DEVELOPER.md): embed GnutellaBun in your own TypeScript app
+
+## License
+
+GnutellaBun is released under the GNU General Public License v3.0. See [LICENSE](LICENSE).

package/bin/gnutella.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env bun
+
+import process from "node:process";
+
+import { errMsg } from "../src/cli_shared";
+import { main as modernMain } from "../src/cli";
+
+async function main() {
+  await modernMain(process.argv.slice(2));
+}
+
+main().catch((e) => {
+  console.error(errMsg(e));
+  process.exit(1);
+});

package/gnutella.json.example

@@ -0,0 +1,18 @@
+{
+  "config": {
+    "listen_ip": "0.0.0.0",
+    "listen_port": 22867,
+    "blocked_ips": [],
+    "ultrapeer": false,
+    "max_ultrapeer_connections": 64,
+    "max_leaf_connections": 64,
+    "log_ignore": [],
+    "data_dir": "."
+  },
+  "state": {
+    "servent_id_hex": "00112233445566778899aabbccddeeff",
+    "peers": {
+      "127.0.0.1:22867": 0
+    }
+  }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "gnutella",
+  "version": "1.0.0",
+  "description": "GnutellaBun is a small Gnutella client for Bun, usable as a CLI or TypeScript library.",
+  "license": "GPL-3.0-only",
+  "bin": {
+    "gnutella": "./bin/gnutella.ts"
+  },
+  "main": "./src/protocol.ts",
+  "types": "./src/protocol.ts",
+  "exports": {
+    ".": "./src/protocol.ts",
+    "./types": "./src/types.ts",
+    "./gwebcache": "./src/gwebcache_client.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "QUICKSTART.md",
+    "CLI.md",
+    "DEVELOPER.md",
+    "LICENSE",
+    "gnutella.json.example"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "keywords": [
+    "gnutella",
+    "p2p",
+    "peer-to-peer",
+    "bun",
+    "cli"
+  ],
+  "homepage": "https://github.com/RickCarlino/gnutella-bun-client#readme",
+  "bugs": {
+    "url": "https://github.com/RickCarlino/gnutella-bun-client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RickCarlino/gnutella-bun-client.git"
+  },
+  "packageManager": "bun@1.3.11",
+  "dependencies": {},
+  "devDependencies": {
+    "@babel/core": "^7.27.1",
+    "@babel/eslint-parser": "^7.27.1",
+    "@babel/preset-typescript": "^7.27.1",
+    "@types/node": "^25.5.0",
+    "bun-types": "^1.3.11",
+    "eslint": "^9.24.0",
+    "jscpd": "^4.0.8",
+    "prettier": "^3.5.3",
+    "ts-unused-exports": "^11.0.1",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "build:all": "./scripts/build-all-targets.sh",
+    "dupcheck": "jscpd",
+    "format:check": "prettier --check AGENTS.md README.md bin package.json tsconfig.json gnutella.json.example src tests scripts --ignore-unknown",
+    "format:write": "prettier --write AGENTS.md README.md bin package.json tsconfig.json gnutella.json.example src tests scripts --ignore-unknown",
+    "lint": "eslint bin src tests --ext .ts",
+    "test": "bun test",
+    "test:integration": "bun test tests/integration/protocol.test.ts",
+    "test:unit": "bun test tests/unit",
+    "typecheck": "tsc --noEmit",
+    "unused-exports": "ts-unused-exports tsconfig.json --excludePathsFromReport=src/protocol.ts --exitWithCount",
+    "fix": "./scripts/fix-all.sh",
+    "verify": "./scripts/verify-all.sh"
+  }
+}