torrent-tui 0.0.2 → 0.0.4

package/README.md

@@ -3,7 +3,9 @@
 **A terminal BitTorrent client for focused download management.** Add `.torrent` files, track active transfers, and manage sessions from a clean keyboard-driven interface.
 
 [![npm version](https://img.shields.io/npm/v/torrent-tui?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/torrent-tui)
-[![CI](https://img.shields.io/github/actions/workflow/status/ryadios/torrent-tui/ci.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/ryadios/torrent-tui/actions/workflows/ci.yml)
+[![gzipped](https://img.shields.io/badge/gzipped-39%20KB-2563eb?style=for-the-badge)](https://www.npmjs.com/package/torrent-tui)
+[![npm unpacked size](https://img.shields.io/npm/unpacked-size/torrent-tui?style=for-the-badge)](https://www.npmjs.com/package/torrent-tui)
+[![CI](https://img.shields.io/github/actions/workflow/status/ryadios/torrent-tui/release.yml?branch=main&style=for-the-badge&logo=github)](https://github.com/ryadios/torrent-tui/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/torrent-tui?style=for-the-badge)](./LICENSE)
 
 [Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) · [Configuration](#configuration) · [Development](#development)
@@ -52,7 +54,8 @@ From inside the app:
 | --- | --- |
 | `j` / `k` or arrow keys | Move selection |
 | `Tab` | Change focus |
-| `a` | Add a `.torrent` file |
+| `a` | Add a `.torrent` file or magnet link |
+| `/` in add dialog | Type a magnet link manually |
 | `Space` | Pause or resume the selected torrent |
 | `d` | Remove the selected torrent |
 | `D` | Remove the selected torrent and downloaded files |
@@ -65,18 +68,25 @@ The package also exposes a few command-line checks around the same torrent engin
 ```bash
 torrent-tui --help
 torrent-tui --version
+torrent-tui file.torrent
+torrent-tui 'magnet:?xt=urn:btih:...'
 torrent-tui file.torrent --verify
 torrent-tui file.torrent --handshake
 torrent-tui file.torrent --download
+torrent-tui 'magnet:?xt=urn:btih:...' --download
 ```
 
 | Command | Description |
 | --- | --- |
 | `torrent-tui` | Start the terminal UI. |
-| `torrent-tui <file.torrent>` | Announce to trackers and print peers. |
+| `torrent-tui <file.torrent>` | Start the TUI and add the torrent. |
+| `torrent-tui <magnet-uri>` | Start the TUI, fetch magnet metadata, cache it, and start the torrent. |
 | `torrent-tui <file.torrent> --verify` | Create storage and verify local pieces. |
 | `torrent-tui <file.torrent> --handshake` | Connect to peers and print a connection summary. |
 | `torrent-tui <file.torrent> --download` | Run the downloader without launching the TUI. |
+| `torrent-tui <magnet-uri> --download` | Fetch magnet metadata, cache it, then run the downloader without launching the TUI. |
+
+Magnet support covers BitTorrent v1 `btih` magnets with trackers (`tr`), explicit peers (`x.pe`), or DHT-discovered peers. After metadata is cached, `--verify` and `--handshake` can use the same magnet URI.
 
 ## Configuration
 
@@ -102,6 +112,52 @@ Resume data is stored under:
 ${XDG_DATA_HOME:-~/.local/share}/torrent-tui/resume
 ```
 
+The session registry is stored at:
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/torrent-tui/session.json
+```
+
+It keeps the list of torrents the TUI should restore on startup.
+
+### Torrent States
+
+The TUI shows detailed per-torrent states while keeping the sidebar filters simple.
+
+| State | Meaning |
+| --- | --- |
+| `Queued` | The `.torrent` was accepted and is waiting for engine startup. |
+| `Metadata` | A magnet link was accepted and metadata is being fetched from peers. |
+| `Checking` | Local files are being checked against torrent piece hashes. |
+| `Connecting` | Trackers were contacted and the client is connecting to peers. |
+| `Downloading` | Pieces are actively being requested or received. |
+| `Stalled` | The torrent is incomplete but has no usable peers right now. Press `Space` to retry. |
+| `Paused` | The active downloader was paused by the user. |
+| `Seeding` | All pieces are present and the torrent can upload to peers. |
+| `Stopped` | The torrent is saved in the session but not running. |
+| `Error` | Startup, storage, or torrent metadata handling failed. |
+
+The `Downloading` sidebar filter includes queued, checking, connecting, downloading, and stalled torrents so active work stays grouped together.
+
+### What Each Setting Does
+
+| Setting | Purpose | When it applies |
+| --- | --- | --- |
+| `downloadPath` | Where torrent payload files are written and verified. | On torrent add, resume, verify, and startup restore. |
+| `torrentFolder` | Folder shown by the add-torrent dialog. | When you open the add dialog. |
+| `maxConnections` | Maximum number of peers the client will connect to per torrent. | During peer discovery and download. |
+
+### Tuning Tips
+
+- Use a fast local SSD for `downloadPath` if you want quicker verification and fewer stalls on reopen.
+- Point `torrentFolder` at the directory where you keep `.torrent` files so adding torrents is faster.
+- Lower `maxConnections` if your network or CPU struggles with many peers; raise it if you want more parallel peer selection.
+- Fresh torrents skip full zero-file verification. Existing files are checked cooperatively, so the TUI should stay responsive during large rechecks.
+- If a torrent stays `Stalled`, the client did not find a usable peer. Try again later with `Space`, or check tracker availability.
+- Settings are read when the app starts. If you edit `settings.json` manually, restart the app to pick up the changes.
+- If the settings file is invalid, torrent-tui falls back to defaults and logs a config warning.
+- `session.json` and the resume files are rewritten automatically as torrent state changes, so you normally do not need to edit them by hand.
+
 ## Status
 
 `0.0.1` is a basic release intended for early CLI usage.
@@ -113,7 +169,8 @@ ${XDG_DATA_HOME:-~/.local/share}/torrent-tui/resume
 | Peer handshakes and piece download | Available |
 | Resume data | Available |
 | Multi-torrent TUI | Available |
-| Magnet links | Not included yet |
+| Magnet links | Available for v1 magnets with tracker, explicit-peer, or DHT discovery |
+| Peer discovery | Trackers, DHT, and PEX |
 | Standalone binaries | Not included yet |
 
 ## Development

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "torrent-tui",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"description": "A Bun-powered terminal BitTorrent client.",
 	"module": "src/index.ts",
 	"type": "module",
@@ -20,9 +20,13 @@
 		"dev": "bun --watch src/index.ts",
 		"check": "bun src/index.ts --download",
 		"smoke": "bin/torrent-tui --help && bin/torrent-tui --version && if bin/torrent-tui nope.txt; then echo \"Expected invalid torrent path to fail\"; exit 1; fi",
+		"bench:startup": "bun scripts/benchmark-startup.ts",
+		"bench:verify": "bun scripts/benchmark-verify.ts",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
 		"typecheck": "tsc --noEmit",
 		"check:fix": "biome check --write --unsafe",
-		"release:check": "bun run typecheck && bun publish --dry-run"
+		"release:check": "bun run typecheck && bun test && bun publish --dry-run"
 	},
 	"keywords": [
 		"bittorrent",

package/src/app.ts

@@ -1,4 +1,8 @@
-import { type CliRenderer, createCliRenderer } from "@opentui/core";
+import {
+	type CliRenderer,
+	createCliRenderer,
+	type PasteEvent,
+} from "@opentui/core";
 import { loadConfig } from "./config";
 import { AppController } from "./controllers/app-controller";
 import { AddTorrentDialog } from "./layout/add-torrent-dialog";
@@ -9,7 +13,9 @@ import { StatusBar } from "./layout/status-bar";
 import { ToastManager } from "./layout/toast-manager";
 import { Store } from "./store";
 import { TorrentBridge } from "./torrent/bridge";
+import { isMagnetUri } from "./torrent/magnet";
 import type { LayoutDimensions } from "./types/layout";
+import { env } from "./utils/env";
 import { calculateLayout } from "./utils/layout";
 
 const INITIAL_STATE = {
@@ -34,10 +40,14 @@ export class App {
 	private layout!: LayoutDimensions;
 	private resizeTimeout: ReturnType<typeof setTimeout> | null = null;
 
-	async start(): Promise<void> {
+	async start(initialTorrentPath?: string): Promise<void> {
 		const config = loadConfig();
 
-		this.renderer = await createCliRenderer({ exitOnCtrlC: true });
+		this.renderer = await createCliRenderer({
+			exitOnCtrlC: true,
+			openConsoleOnError: env.SHOW_CONSOLE,
+			useConsole: env.SHOW_CONSOLE,
+		});
 		this.store = new Store(INITIAL_STATE);
 		this.layout = calculateLayout(this.renderer.width, this.renderer.height);
 		this.bridge = new TorrentBridge(this.store, config);
@@ -62,6 +72,7 @@ export class App {
 			this.store,
 			this.sidebar,
 			this.contentWindow,
+			this.statusBar,
 			this.toastManager,
 		);
 		// Wire ConfirmDialog — callbacks are set inside the controller setter
@@ -80,6 +91,10 @@ export class App {
 			return this.addDialog.handleInput(key);
 		};
 
+		this.controller.onDialogPaste = (event: PasteEvent) => {
+			return this.addDialog.handlePaste(event);
+		};
+
 		this.controller.onQuit = async () => {
 			await this.bridge.stopAll();
 			this.renderer.destroy();
@@ -101,41 +116,27 @@ export class App {
 			this.bridge.removeTorrent(id, deleteFiles);
 		};
 
-		this.addDialog.onSelect = async (filePath) => {
+		this.addDialog.onSelect = (filePath) => {
 			this.controller.focusMode = "global";
 			const filename = filePath.split("/").pop() ?? filePath;
-			this.toastManager.show({
-				id: `add-${Date.now()}`,
-				type: "info",
-				title: "Adding torrent",
-				message: filename,
-			});
+			this.renderer.requestRender();
 
-			try {
-				await this.bridge.addTorrent(filePath);
-				this.toastManager.show({
-					id: `added-${Date.now()}`,
-					type: "success",
-					title: "Download started",
-					message: filename,
-				});
-			} catch (err) {
-				this.toastManager.show({
-					id: `err-${Date.now()}`,
-					type: "error",
-					title: "Failed to add",
-					message: err instanceof Error ? err.message : String(err),
-				});
-			}
+			setTimeout(() => {
+				this.addTorrentInBackground(filePath, filename);
+			}, 0);
 		};
 
-		this.store.subscribe((state) => {
-			this.statusBar.update(state);
-		});
-
 		await this.bridge.restoreSession();
 		this.controller.start();
 
+		if (initialTorrentPath) {
+			const filename =
+				initialTorrentPath.split("/").pop() ?? initialTorrentPath;
+			setTimeout(() => {
+				this.addTorrentInBackground(initialTorrentPath, filename);
+			}, 0);
+		}
+
 		this.renderer.on("resize", (width: number, height: number) => {
 			this.handleResize(width, height);
 		});
@@ -154,4 +155,40 @@ export class App {
 			this.confirmDialog.updateLayout(this.layout);
 		}, 100);
 	}
+
+	private async addTorrentInBackground(
+		input: string,
+		filename: string,
+	): Promise<void> {
+		try {
+			const result = isMagnetUri(input)
+				? await this.bridge.addMagnet(input)
+				: await this.bridge.addTorrent(input);
+			this.toastManager.show({
+				id: `added-${Date.now()}`,
+				type: result.added ? "success" : "info",
+				title: result.added ? "Torrent added" : "Torrent already added",
+				message: result.name || filename,
+			});
+			this.renderer.requestRender();
+
+			if (result.added) {
+				this.bridge.startTorrent(result.id).catch((err: unknown) => {
+					this.toastManager.show({
+						id: `start-err-${Date.now()}`,
+						type: "error",
+						title: "Failed to start",
+						message: err instanceof Error ? err.message : String(err),
+					});
+				});
+			}
+		} catch (err) {
+			this.toastManager.show({
+				id: `err-${Date.now()}`,
+				type: "error",
+				title: "Failed to add",
+				message: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
 }

package/src/config/index.ts

@@ -1,7 +1,9 @@
 // Config loader - reads from ~/.config/torrent-tui/settings.json
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { getConfigDir, getConfigPath } from "../utils/paths";
+import { existsSync, readFileSync } from "node:fs";
+import { log } from "../torrent/metadata";
+import { writeJsonAtomic } from "../utils/json";
+import { getConfigPath } from "../utils/paths";
 import { type AppSettings, DEFAULT_SETTINGS, settingsSchema } from "./settings";
 
 const SETTINGS_FILE = "settings.json";
@@ -24,18 +26,14 @@ export function loadConfig(): AppSettings {
 			return result.data;
 		}
 
+		log("config", "invalid settings file — using defaults");
 		return { ...DEFAULT_SETTINGS };
 	} catch {
+		log("config", "could not read settings file — using defaults");
 		return { ...DEFAULT_SETTINGS };
 	}
 }
 
 export function saveConfig(settings: AppSettings): void {
-	try {
-		mkdirSync(getConfigDir(), { recursive: true });
-		const configPath = getConfigPath(SETTINGS_FILE);
-		writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
-	} catch {
-		// Silently fail
-	}
+	writeJsonAtomic(getConfigPath(SETTINGS_FILE), settings);
 }

package/src/constants/index.ts

@@ -3,7 +3,7 @@ export const APP_NAME = "torrent-tui";
 export const SIDEBAR_WIDTH = 20;
 
 export const SIDEBAR_ITEMS = {
-	status: ["All", "Downloading", "Seeding", "Completed", "Stopped"],
+	status: ["All", "Downloading", "Paused", "Seeding", "Completed", "Stopped"],
 } as const;
 
 export type SidebarSection = keyof typeof SIDEBAR_ITEMS;