torrent-tui 0.0.3 → 0.0.5

package/README.md

@@ -3,7 +3,6 @@
 **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)
-[![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)
@@ -53,33 +52,48 @@ From inside the app:
 | Key | Action |
 | --- | --- |
 | `j` / `k` or arrow keys | Move selection |
-| `Tab` | Change focus |
-| `a` | Add a `.torrent` file |
+| `Tab` / `Shift+Tab` | Change focus |
+| `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 |
 | `q` | Quit |
 
+The detail panel has `Pieces`, `Peers`, and `Files` tabs. Focus it with `Tab`, then use `h` / `l`, `[` / `]`, or left/right arrows to switch tabs. Multi-file torrents open a file picker before download; use `Space` to toggle a file, `a` to select all, `n` to select none, and `Enter` to confirm.
+
 ## Commands
 
-The package also exposes a few command-line checks around the same torrent engine:
+The package also exposes command-line workflows around the same torrent engine:
 
 ```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
+torrent-tui file.torrent --info
+torrent-tui file.torrent --info --json
+torrent-tui 'magnet:?xt=urn:btih:...' --info
 ```
 
 | Command | Description |
 | --- | --- |
 | `torrent-tui` | Start the terminal UI. |
 | `torrent-tui <file.torrent>` | Start the TUI and add the torrent. |
-| `torrent-tui <file.torrent> --verify` | Create storage and verify local pieces. |
+| `torrent-tui <magnet-uri>` | Start the TUI, fetch magnet metadata, cache it, and start the torrent. |
+| `torrent-tui <file.torrent> --verify` | Create storage, verify local pieces, and print a tracker summary. |
 | `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. |
+| `torrent-tui <file.torrent> --info` | Print torrent metadata without launching the TUI. |
+| `torrent-tui <file.torrent> --info --json` | Print torrent metadata as machine-readable JSON. |
+| `torrent-tui <magnet-uri> --info` | Print cached magnet metadata 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`, `--handshake`, and `--info` can use the same magnet URI.
 
 ## Configuration
 
@@ -95,7 +109,18 @@ Default settings:
 {
 	"downloadPath": "~/Downloads",
 	"maxConnections": 50,
-	"torrentFolder": "~/Downloads"
+	"torrentFolder": "~/Downloads",
+	"downloadRateLimitBps": 0,
+	"uploadRateLimitBps": 0,
+	"enableWebSeeds": true,
+	"maxWebSeedConnections": 3,
+	"webSeedMaxRequestBytes": 16777216,
+	"blocklistEnabled": false,
+	"blocklistPaths": [],
+	"blocklistUrl": "",
+	"blocklistRefreshHours": 168,
+	"encryption": "preferred",
+	"enableLsd": true
 }
 ```
 
@@ -120,6 +145,7 @@ The TUI shows detailed per-torrent states while keeping the sidebar filters simp
 | 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. |
@@ -127,6 +153,7 @@ The TUI shows detailed per-torrent states while keeping the sidebar filters simp
 | `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. |
+| `Missing` | Previously tracked files are missing from disk after restore or recheck. |
 | `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.
@@ -138,12 +165,26 @@ The `Downloading` sidebar filter includes queued, checking, connecting, download
 | `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. |
+| `downloadRateLimitBps` | Download speed cap in bytes per second. `0` means unlimited. | During downloads. |
+| `uploadRateLimitBps` | Upload speed cap in bytes per second. `0` means unlimited. | During uploads to peers. |
+| `enableWebSeeds` | Enables BEP 19 HTTP web seed downloads. | For torrents with `url-list` web seeds. |
+| `maxWebSeedConnections` | Maximum concurrent web seed workers. | During web seed downloads. |
+| `webSeedMaxRequestBytes` | Largest HTTP range request sent to a web seed. | During web seed downloads. |
+| `blocklistEnabled` | Enables peer blocklist filtering. | Before peer connections are accepted or opened. |
+| `blocklistPaths` | Local blocklist files to load. | When blocklists are enabled. |
+| `blocklistUrl` | Optional remote blocklist URL to cache and load. | When blocklists are enabled. |
+| `blocklistRefreshHours` | Remote blocklist cache refresh interval. | When `blocklistUrl` is configured. |
+| `encryption` | Peer encryption policy: `allowed`, `preferred`, or `required`. | During peer connection setup. |
+| `enableLsd` | Enables local peer discovery on the LAN. | For non-private torrents. |
 
 ### 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.
+- Use `downloadRateLimitBps` and `uploadRateLimitBps` when you need bandwidth caps.
+- Set `encryption` to `required` only if you want to reject plaintext peers.
+- Enable blocklists only with lists you trust; malformed or unreachable lists are ignored or fall back to cached data.
 - 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.
@@ -152,7 +193,7 @@ The `Downloading` sidebar filter includes queued, checking, connecting, download
 
 ## Status
 
-`0.0.1` is a basic release intended for early CLI usage.
+`torrent-tui` is an early Bun-first torrent client with a TUI and CLI inspection workflows.
 
 | Area | Status |
 | --- | --- |
@@ -161,7 +202,16 @@ The `Downloading` sidebar filter includes queued, checking, connecting, download
 | 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 |
+| Detail panel | Pieces, peers, and files tabs |
+| File selection | Available for multi-file torrents before download |
+| Engine controls | Download/upload rate limits and max peer connections |
+| Peer discovery | Trackers, DHT, PEX, and LSD |
+| Web seeds | BEP 19 HTTP web seeds |
+| Peer filtering | Local or cached remote blocklists |
+| Protocol encryption | MSE/PE with allowed, preferred, or required policy |
+| Padding files | BEP 47 padding files are hidden from payload file lists |
+| CLI inspection | `--info`, `--info --json`, and man page packaging |
 | Standalone binaries | Not included yet |
 
 ## Development
@@ -175,7 +225,9 @@ Before opening a PR:
 
 ```bash
 bun run typecheck
-bun publish --dry-run
+bun test
+bun run smoke
+npm publish --dry-run
 ```
 
 For formatting and lint fixes:
@@ -188,12 +240,14 @@ bun run check:fix
 
 Releases are published from GitHub Actions with generated GitHub release notes.
 
-1. Update `package.json` and `src/constants/index.ts` to the new version.
+1. Update `package.json` to the new version.
 2. Run local checks:
 
    ```bash
    bun run typecheck
-   bun publish --dry-run
+   bun test
+   bun run smoke
+   npm publish --dry-run
    ```
 
 3. Commit and push the version change.

package/man/torrent-tui.1

@@ -0,0 +1,61 @@
+.TH TORRENT-TUI 1
+.SH NAME
+torrent-tui \- Bun-powered terminal BitTorrent client
+.SH SYNOPSIS
+.B torrent-tui
+[\fIfile.torrent\fR|\fImagnet-uri\fR]
+[\fB--verify\fR|\fB--handshake\fR|\fB--download\fR|\fB--info\fR]
+[\fB--json\fR]
+.SH DESCRIPTION
+.B torrent-tui
+starts a terminal BitTorrent client for adding, inspecting, and managing torrents.
+It can also run selected torrent engine workflows directly from the command line.
+.SH OPTIONS
+.TP
+.B --help, -h
+Show command help.
+.TP
+.B --version, -v
+Print the package version.
+.TP
+.B --verify
+Verify local pieces for a torrent and print a tracker summary.
+.TP
+.B --handshake
+Contact trackers, connect to peers, and print a handshake summary.
+.TP
+.B --download
+Download a torrent without starting the terminal UI.
+.TP
+.B --info
+Print torrent metadata without starting the terminal UI.
+.TP
+.B --json
+Print machine-readable JSON for
+.BR --info .
+.SH COMMANDS
+.TP
+.B torrent-tui
+Start the terminal UI.
+.TP
+.B torrent-tui file.torrent
+Start the terminal UI and add a torrent.
+.TP
+.B torrent-tui magnet-uri
+Start the terminal UI and fetch magnet metadata.
+.TP
+.B torrent-tui file.torrent --info
+Print a framed metadata summary with padded lowercase labels, matching other
+command summary output.
+.TP
+.B torrent-tui file.torrent --info --json
+Print the same metadata as pretty JSON for scripts.
+.SH FILES
+.TP
+.I ${XDG_CONFIG_HOME:-~/.config}/torrent-tui/settings.json
+User settings.
+.TP
+.I ${XDG_DATA_HOME:-~/.local/share}/torrent-tui/session.json
+Session registry restored by the TUI.
+.SH SEE ALSO
+.BR bun (1)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "torrent-tui",
-	"version": "0.0.3",
+	"version": "0.0.5",
 	"description": "A Bun-powered terminal BitTorrent client.",
 	"module": "src/index.ts",
 	"type": "module",
@@ -9,8 +9,12 @@
 	"bin": {
 		"torrent-tui": "bin/torrent-tui"
 	},
+	"man": [
+		"man/torrent-tui.1"
+	],
 	"files": [
 		"bin",
+		"man",
 		"src",
 		"README.md",
 		"LICENSE"
@@ -18,15 +22,16 @@
 	"scripts": {
 		"start": "bun src/index.ts",
 		"dev": "bun --watch src/index.ts",
-		"check": "bun src/index.ts --download",
+		"check": "bun run typecheck && bun test",
 		"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:webseed": "bun scripts/benchmark-webseed.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 test && bun publish --dry-run"
+		"release:check": "bun run typecheck && bun test && bun run smoke && npm publish --dry-run"
 	},
 	"keywords": [
 		"bittorrent",

package/src/app.ts

@@ -1,15 +1,22 @@
-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";
 import { ConfirmDialog } from "./layout/confirm-dialog";
 import { ContentWindow } from "./layout/content-window";
+import { FilePickerDialog } from "./layout/file-picker-dialog";
 import { Sidebar } from "./layout/sidebar";
 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 = {
@@ -31,13 +38,18 @@ export class App {
 	private bridge!: TorrentBridge;
 	private addDialog!: AddTorrentDialog;
 	private confirmDialog!: ConfirmDialog;
+	private filePickerDialog!: FilePickerDialog;
 	private layout!: LayoutDimensions;
 	private resizeTimeout: ReturnType<typeof setTimeout> | null = null;
 
 	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);
@@ -56,6 +68,7 @@ export class App {
 			config.torrentFolder,
 		);
 		this.confirmDialog = new ConfirmDialog(this.renderer, this.layout);
+		this.filePickerDialog = new FilePickerDialog(this.renderer, this.layout);
 
 		this.controller = new AppController(
 			this.renderer,
@@ -74,13 +87,36 @@ export class App {
 		};
 
 		this.controller.onDialogClose = () => {
-			this.addDialog.close();
+			if (this.filePickerDialog.getIsOpen()) {
+				this.filePickerDialog.confirmWithAllFiles();
+			} else {
+				this.addDialog.close();
+			}
 		};
 
 		this.controller.onDialogInput = (key) => {
+			if (this.filePickerDialog.getIsOpen())
+				return this.filePickerDialog.handleInput(key);
 			return this.addDialog.handleInput(key);
 		};
 
+		this.filePickerDialog.onConfirm = (id, selectedIndices) => {
+			this.controller.focusMode = "global";
+			this.bridge.setFileSelection(id, selectedIndices);
+			this.bridge.startTorrent(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),
+				});
+			});
+		};
+
+		this.controller.onDialogPaste = (event: PasteEvent) => {
+			return this.addDialog.handlePaste(event);
+		};
+
 		this.controller.onQuit = async () => {
 			await this.bridge.stopAll();
 			this.renderer.destroy();
@@ -139,15 +175,18 @@ export class App {
 			this.toastManager.updateLayout(this.layout);
 			this.addDialog.updateLayout(this.layout);
 			this.confirmDialog.updateLayout(this.layout);
+			this.filePickerDialog.updateLayout(this.layout);
 		}, 100);
 	}
 
 	private async addTorrentInBackground(
-		filePath: string,
+		input: string,
 		filename: string,
 	): Promise<void> {
 		try {
-			const result = await this.bridge.addTorrent(filePath);
+			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",
@@ -157,14 +196,22 @@ export class App {
 			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),
+				const torrent = this.store
+					.getState()
+					.torrents.find((t) => t.id === result.id);
+				if (torrent && torrent.files.length > 1) {
+					this.controller.focusMode = "dialog";
+					this.filePickerDialog.open(result.id, torrent.files, torrent.name);
+				} else {
+					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({

package/src/cli/info.ts

@@ -0,0 +1,133 @@
+import { readFileSync } from "node:fs";
+import { decode, type BencodeValue } from "../torrent/parser";
+import { TorrentMetadata } from "../torrent/metadata";
+
+export interface TorrentInfoFile {
+	path: string;
+	length: number;
+	offset: number;
+	padding?: boolean;
+}
+
+export interface TorrentInfo {
+	name: string;
+	infoHash: string;
+	totalSize: number;
+	pieceLength: number;
+	pieceCount: number;
+	private: boolean;
+	isMultiFile: boolean;
+	trackers: string[][];
+	webSeeds: string[];
+	nodes: Array<{ ip: string; port: number }>;
+	files: TorrentInfoFile[];
+}
+
+export function readTorrentInfo(torrentPath: string): TorrentInfo {
+	const raw = new Uint8Array(readFileSync(torrentPath));
+	return torrentInfoFromBytes(raw);
+}
+
+export function torrentInfoFromBytes(raw: Uint8Array): TorrentInfo {
+	const decoded = decode(raw);
+	if (
+		typeof decoded !== "object" ||
+		decoded === null ||
+		Array.isArray(decoded) ||
+		decoded instanceof Uint8Array
+	) {
+		throw new Error("Invalid torrent file");
+	}
+	return torrentInfoFromMetadata(
+		new TorrentMetadata(decoded as { [key: string]: BencodeValue }, raw),
+	);
+}
+
+export function torrentInfoFromMetadata(metadata: TorrentMetadata): TorrentInfo {
+	return {
+		name: metadata.name,
+		infoHash: Buffer.from(metadata.infoHash).toString("hex"),
+		totalSize: metadata.totalSize,
+		pieceLength: metadata.pieceLength,
+		pieceCount: metadata.pieceCount,
+		private: metadata.private,
+		isMultiFile: metadata.isMultiFile,
+		trackers: metadata.announceList.map((tier) => [...tier]),
+		webSeeds: [...metadata.webSeeds],
+		nodes: metadata.nodes.map((node) => ({ ...node })),
+		files: metadata.files.map((file) => ({ ...file })),
+	};
+}
+
+export function formatTorrentInfo(info: TorrentInfo): string {
+	const lines = [
+		line(),
+		"  Torrent Info",
+		line(),
+		row("name", info.name),
+		row("info-hash", info.infoHash),
+		row("size", `${formatBytes(info.totalSize)} (${info.totalSize} bytes)`),
+		row("pieces", `${info.pieceCount} x ${formatBytes(info.pieceLength)}`),
+		row("private", info.private ? "yes" : "no"),
+		row("mode", info.isMultiFile ? "multi-file" : "single-file"),
+		"",
+		"  trackers",
+	];
+
+	if (info.trackers.length === 0) {
+		lines.push("    none");
+	} else {
+		for (let i = 0; i < info.trackers.length; i++) {
+			const tier = info.trackers[i] ?? [];
+			lines.push(`    tier ${i + 1}`);
+			for (const tracker of tier) lines.push(`      ${tracker}`);
+		}
+	}
+
+	lines.push("", "  web-seeds");
+	if (info.webSeeds.length === 0) {
+		lines.push("    none");
+	} else {
+		for (const seed of info.webSeeds) lines.push(`    ${seed}`);
+	}
+
+	lines.push("", "  dht-nodes");
+	if (info.nodes.length === 0) {
+		lines.push("    none");
+	} else {
+		for (const node of info.nodes) lines.push(`    ${node.ip}:${node.port}`);
+	}
+
+	lines.push("", "  files");
+	for (const file of info.files) {
+		lines.push(`    ${formatBytes(file.length).padStart(9)}  ${file.path}`);
+	}
+
+	lines.push(line());
+	return `${lines.join("\n")}\n`;
+}
+
+export function formatTorrentInfoJson(info: TorrentInfo): string {
+	return `${JSON.stringify(info, null, "\t")}\n`;
+}
+
+function formatBytes(bytes: number): string {
+	const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+	let value = bytes;
+	let unit = 0;
+	while (value >= 1024 && unit < units.length - 1) {
+		value /= 1024;
+		unit++;
+	}
+	const label = units[unit] ?? "B";
+	if (unit === 0) return `${bytes} ${label}`;
+	return `${value.toFixed(value >= 10 ? 1 : 2)} ${label}`;
+}
+
+function line(): string {
+	return "-".repeat(80);
+}
+
+function row(label: string, value: string): string {
+	return `  ${label.padEnd(10)}  ${value}`;
+}

package/src/cli/parse.ts

@@ -0,0 +1,82 @@
+export type CliAction =
+	| "tui"
+	| "help"
+	| "version"
+	| "verify"
+	| "handshake"
+	| "download"
+	| "info";
+
+export interface CliCommand {
+	action: CliAction;
+	input?: string;
+	json: boolean;
+}
+
+const ACTION_FLAGS = new Map<string, CliAction>([
+	["--verify", "verify"],
+	["--handshake", "handshake"],
+	["--download", "download"],
+	["--info", "info"],
+]);
+
+const HELP_FLAGS = new Set(["--help", "-h"]);
+const VERSION_FLAGS = new Set(["--version", "-v"]);
+const VALUELESS_FLAGS = new Set([
+	...HELP_FLAGS,
+	...VERSION_FLAGS,
+	...ACTION_FLAGS.keys(),
+	"--json",
+]);
+
+export function parseCliArgs(args: string[]): CliCommand {
+	if (args.some((arg) => HELP_FLAGS.has(arg))) {
+		ensureOnlyKnownFlags(args);
+		return { action: "help", json: false };
+	}
+	if (args.some((arg) => VERSION_FLAGS.has(arg))) {
+		ensureOnlyKnownFlags(args);
+		return { action: "version", json: false };
+	}
+
+	ensureOnlyKnownFlags(args);
+
+	const json = args.includes("--json");
+	const actions = args
+		.filter((arg) => ACTION_FLAGS.has(arg))
+		.map((arg) => ACTION_FLAGS.get(arg) as CliAction);
+	if (actions.length > 1) {
+		throw new Error(`Choose only one action flag: ${actions.join(", ")}`);
+	}
+	if (json && actions[0] !== "info") {
+		throw new Error("--json can only be used with --info");
+	}
+
+	const inputs = args.filter((arg) => !VALUELESS_FLAGS.has(arg));
+	if (inputs.length > 1) {
+		throw new Error(`Expected one torrent or magnet argument, got ${inputs.length}`);
+	}
+
+	const input = inputs[0];
+	const action = actions[0] ?? "tui";
+	if (action !== "tui" && !input) {
+		throw new Error(`Missing torrent or magnet argument for ${flagForAction(action)}`);
+	}
+
+	return { action, input, json };
+}
+
+function ensureOnlyKnownFlags(args: string[]): void {
+	for (const arg of args) {
+		if (arg.startsWith("-") && !VALUELESS_FLAGS.has(arg)) {
+			throw new Error(`Unknown option: ${arg}`);
+		}
+	}
+}
+
+function flagForAction(action: CliAction): string {
+	for (const [flag, flagAction] of ACTION_FLAGS) {
+		if (flagAction === action) return flag;
+	}
+	return action;
+}

package/src/config/settings.ts

@@ -4,6 +4,17 @@ export const settingsSchema = z.object({
 	downloadPath: z.string().default("~/Downloads"),
 	maxConnections: z.number().min(1).max(500).default(50),
 	torrentFolder: z.string().default("~/Downloads"),
+	downloadRateLimitBps: z.number().min(0).default(0),
+	uploadRateLimitBps: z.number().min(0).default(0),
+	enableWebSeeds: z.boolean().default(true),
+	maxWebSeedConnections: z.number().min(0).max(20).default(3),
+	webSeedMaxRequestBytes: z.number().min(16_384).default(16_777_216),
+	blocklistEnabled: z.boolean().default(false),
+	blocklistPaths: z.array(z.string()).default([]),
+	blocklistUrl: z.string().default(""),
+	blocklistRefreshHours: z.number().min(1).default(168),
+	encryption: z.enum(["allowed", "preferred", "required"]).default("preferred"),
+	enableLsd: z.boolean().default(true),
 });
 
 export type AppSettings = z.infer<typeof settingsSchema>;
@@ -12,4 +23,15 @@ export const DEFAULT_SETTINGS: AppSettings = {
 	downloadPath: "~/Downloads",
 	maxConnections: 50,
 	torrentFolder: "~/Downloads",
+	downloadRateLimitBps: 0,
+	uploadRateLimitBps: 0,
+	enableWebSeeds: true,
+	maxWebSeedConnections: 3,
+	webSeedMaxRequestBytes: 16_777_216,
+	blocklistEnabled: false,
+	blocklistPaths: [],
+	blocklistUrl: "",
+	blocklistRefreshHours: 168,
+	encryption: "preferred",
+	enableLsd: true,
 };

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;