torrent-tui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aditya
+
+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

@@ -0,0 +1,156 @@
+# torrent-tui
+
+**A Bun-powered terminal BitTorrent client.** Add `.torrent` files, manage active downloads, and inspect transfer state from a focused TUI.
+
+[![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)
+[![license](https://img.shields.io/npm/l/torrent-tui?style=for-the-badge)](./LICENSE)
+
+[Install](#install) · [Quickstart](#quickstart) · [Commands](#commands) · [Configuration](#configuration) · [Development](#development)
+
+> [!NOTE]
+> `torrent-tui` currently requires [Bun](https://bun.sh). Standalone binaries are planned after the npm CLI release path is stable.
+
+> [!IMPORTANT]
+> Use torrent clients only with content you have the right to download or share. `torrent-tui` is a client implementation, not a content source.
+
+## Install
+
+Run without installing:
+
+```bash
+bunx torrent-tui@latest
+```
+
+Or install globally:
+
+```bash
+bun add -g torrent-tui
+torrent-tui
+```
+
+> [!TIP]
+> If the global command is not found, add Bun's global bin directory to your shell path:
+>
+> ```bash
+> export PATH="$HOME/.bun/bin:$HOME/.cache/.bun/bin:$PATH"
+> ```
+
+## Quickstart
+
+Start the TUI:
+
+```bash
+torrent-tui
+```
+
+From inside the app:
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` or arrow keys | Move selection |
+| `Tab` | Change focus |
+| `a` | Add a `.torrent` file |
+| `Space` | Pause or resume the selected torrent |
+| `d` | Remove the selected torrent |
+| `D` | Remove the selected torrent and downloaded files |
+| `q` | Quit |
+
+## Commands
+
+The package also exposes a few command-line checks around the same torrent engine:
+
+```bash
+torrent-tui --help
+torrent-tui --version
+torrent-tui file.torrent --verify
+torrent-tui file.torrent --handshake
+torrent-tui file.torrent --download
+```
+
+| Command | Description |
+| --- | --- |
+| `torrent-tui` | Start the terminal UI. |
+| `torrent-tui <file.torrent>` | Announce to trackers and print peers. |
+| `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. |
+
+## Configuration
+
+Settings are stored at:
+
+```text
+${XDG_CONFIG_HOME:-~/.config}/torrent-tui/settings.json
+```
+
+Default settings:
+
+```json
+{
+	"downloadPath": "~/Downloads",
+	"maxConnections": 50,
+	"torrentFolder": "~/Downloads"
+}
+```
+
+Resume data is stored under:
+
+```text
+${XDG_DATA_HOME:-~/.local/share}/torrent-tui/resume
+```
+
+## Status
+
+`0.0.1` is a basic release intended for early CLI usage.
+
+| Area | Status |
+| --- | --- |
+| `.torrent` metadata parsing | Available |
+| HTTP and UDP trackers | Available |
+| Peer handshakes and piece download | Available |
+| Resume data | Available |
+| Multi-torrent TUI | Available |
+| Magnet links | Not included yet |
+| Standalone binaries | Not included yet |
+
+## Development
+
+```bash
+bun install
+bun run dev
+```
+
+Before opening a PR:
+
+```bash
+bun run typecheck
+bun publish --dry-run
+```
+
+For formatting and lint fixes:
+
+```bash
+bun run check:fix
+```
+
+## Release Flow
+
+Releases are published from GitHub Actions with generated GitHub release notes.
+
+1. Update `package.json` and `src/constants/index.ts` to the new version.
+2. Run local checks:
+
+   ```bash
+   bun run typecheck
+   bun publish --dry-run
+   ```
+
+3. Commit and push the version change.
+4. Run the **Release** workflow manually with the version number.
+
+The workflow publishes to npm with trusted publishing, creates `vX.Y.Z`, and creates a GitHub release with `--generate-notes`.
+
+## License
+
+MIT

package/bin/torrent-tui

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const binDir = dirname(fileURLToPath(import.meta.url));
+const entrypoint = join(binDir, "../src/index.ts");
+const bun = process.platform === "win32" ? "bun.exe" : "bun";
+
+const result = spawnSync(bun, [entrypoint, ...process.argv.slice(2)], {
+	stdio: "inherit",
+});
+
+if (result.error) {
+	if ("code" in result.error && result.error.code === "ENOENT") {
+		console.error("torrent-tui requires Bun. Install it from https://bun.sh");
+	} else {
+		console.error(result.error.message);
+	}
+	process.exitCode = 1;
+} else if (result.signal) {
+	process.kill(process.pid, result.signal);
+} else {
+	process.exitCode = result.status ?? 0;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "torrent-tui",
+	"version": "0.0.1",
+	"description": "A Bun-powered terminal BitTorrent client.",
+	"module": "src/index.ts",
+	"type": "module",
+	"private": false,
+	"packageManager": "bun@1.2.21",
+	"bin": {
+		"torrent-tui": "bin/torrent-tui"
+	},
+	"files": [
+		"bin",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"start": "bun src/index.ts",
+		"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",
+		"typecheck": "tsc --noEmit",
+		"check:fix": "biome check --write --unsafe",
+		"release:check": "bun run typecheck && bun publish --dry-run"
+	},
+	"keywords": [
+		"bittorrent",
+		"torrent",
+		"tui",
+		"terminal",
+		"cli",
+		"bun",
+		"opentui"
+	],
+	"author": "Aditya",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ryadios/torrent-tui.git"
+	},
+	"bugs": {
+		"url": "https://github.com/ryadios/torrent-tui/issues"
+	},
+	"homepage": "https://github.com/ryadios/torrent-tui#readme",
+	"engines": {
+		"bun": ">=1.0.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.8",
+		"@types/bun": "latest",
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@opentui/core": "^0.1.90",
+		"zod": "^3.23.8"
+	}
+}

package/src/app.ts

@@ -0,0 +1,157 @@
+import { type CliRenderer, createCliRenderer } 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 { 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 type { LayoutDimensions } from "./types/layout";
+import { calculateLayout } from "./utils/layout";
+
+const INITIAL_STATE = {
+	selectedIndex: 0,
+	selectedView: "All",
+	torrents: [],
+	totalDownloadBps: 0,
+	totalUploadBps: 0,
+};
+
+export class App {
+	private renderer!: CliRenderer;
+	private store!: Store;
+	private sidebar!: Sidebar;
+	private contentWindow!: ContentWindow;
+	private statusBar!: StatusBar;
+	private toastManager!: ToastManager;
+	private controller!: AppController;
+	private bridge!: TorrentBridge;
+	private addDialog!: AddTorrentDialog;
+	private confirmDialog!: ConfirmDialog;
+	private layout!: LayoutDimensions;
+	private resizeTimeout: ReturnType<typeof setTimeout> | null = null;
+
+	async start(): Promise<void> {
+		const config = loadConfig();
+
+		this.renderer = await createCliRenderer({ exitOnCtrlC: true });
+		this.store = new Store(INITIAL_STATE);
+		this.layout = calculateLayout(this.renderer.width, this.renderer.height);
+		this.bridge = new TorrentBridge(this.store, config);
+
+		this.sidebar = new Sidebar(this.renderer, this.store, this.layout);
+		this.contentWindow = new ContentWindow(
+			this.renderer,
+			this.store,
+			this.layout,
+		);
+		this.statusBar = new StatusBar(this.renderer, this.layout);
+		this.toastManager = new ToastManager(this.renderer, this.layout);
+		this.addDialog = new AddTorrentDialog(
+			this.renderer,
+			this.layout,
+			config.torrentFolder,
+		);
+		this.confirmDialog = new ConfirmDialog(this.renderer, this.layout);
+
+		this.controller = new AppController(
+			this.renderer,
+			this.store,
+			this.sidebar,
+			this.contentWindow,
+			this.toastManager,
+		);
+		// Wire ConfirmDialog — callbacks are set inside the controller setter
+		this.controller.confirmDialog = this.confirmDialog;
+
+		// Wire controller callbacks
+		this.controller.onAddTorrent = () => {
+			this.addDialog.open();
+		};
+
+		this.controller.onDialogClose = () => {
+			this.addDialog.close();
+		};
+
+		this.controller.onDialogInput = (key) => {
+			return this.addDialog.handleInput(key);
+		};
+
+		this.controller.onQuit = async () => {
+			await this.bridge.stopAll();
+			this.renderer.destroy();
+		};
+
+		this.controller.onPauseTorrent = (id) => {
+			this.bridge.pauseTorrent(id);
+		};
+
+		this.controller.onResumeTorrent = (id) => {
+			this.bridge.resumeTorrent(id);
+		};
+
+		this.controller.onStartTorrent = (id) => {
+			this.bridge.startTorrent(id);
+		};
+
+		this.controller.onRemoveTorrent = (id, deleteFiles) => {
+			this.bridge.removeTorrent(id, deleteFiles);
+		};
+
+		this.addDialog.onSelect = async (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,
+			});
+
+			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),
+				});
+			}
+		};
+
+		this.store.subscribe((state) => {
+			this.statusBar.update(state);
+		});
+
+		await this.bridge.restoreSession();
+		this.controller.start();
+
+		this.renderer.on("resize", (width: number, height: number) => {
+			this.handleResize(width, height);
+		});
+	}
+
+	private handleResize(width: number, height: number): void {
+		if (this.resizeTimeout) clearTimeout(this.resizeTimeout);
+		this.resizeTimeout = setTimeout(() => {
+			this.resizeTimeout = null;
+			this.layout = calculateLayout(width, height);
+			this.sidebar.updateLayout(this.layout);
+			this.contentWindow.updateLayout(this.layout);
+			this.statusBar.updateLayout(this.layout);
+			this.toastManager.updateLayout(this.layout);
+			this.addDialog.updateLayout(this.layout);
+			this.confirmDialog.updateLayout(this.layout);
+		}, 100);
+	}
+}

package/src/config/index.ts

@@ -0,0 +1,41 @@
+// Config loader - reads from ~/.config/torrent-tui/settings.json
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { getConfigDir, getConfigPath } from "../utils/paths";
+import { type AppSettings, DEFAULT_SETTINGS, settingsSchema } from "./settings";
+
+const SETTINGS_FILE = "settings.json";
+
+export function loadConfig(): AppSettings {
+	const configPath = getConfigPath(SETTINGS_FILE);
+
+	if (!existsSync(configPath)) {
+		// Create config dir and save default settings on first run
+		saveConfig(DEFAULT_SETTINGS);
+		return { ...DEFAULT_SETTINGS };
+	}
+
+	try {
+		const content = readFileSync(configPath, "utf-8");
+		const raw = JSON.parse(content);
+		const result = settingsSchema.safeParse(raw);
+
+		if (result.success) {
+			return result.data;
+		}
+
+		return { ...DEFAULT_SETTINGS };
+	} catch {
+		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
+	}
+}

package/src/config/settings.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+
+export const settingsSchema = z.object({
+	downloadPath: z.string().default("~/Downloads"),
+	maxConnections: z.number().min(1).max(500).default(50),
+	torrentFolder: z.string().default("~/Downloads"),
+});
+
+export type AppSettings = z.infer<typeof settingsSchema>;
+
+export const DEFAULT_SETTINGS: AppSettings = {
+	downloadPath: "~/Downloads",
+	maxConnections: 50,
+	torrentFolder: "~/Downloads",
+};

package/src/constants/index.ts

@@ -0,0 +1,16 @@
+export const APP_NAME = "torrent-tui";
+export const VERSION = "0.0.1";
+
+export const SIDEBAR_WIDTH = 20;
+
+export const SIDEBAR_ITEMS = {
+	status: ["All", "Downloading", "Seeding", "Completed", "Stopped"],
+} as const;
+
+export type SidebarSection = keyof typeof SIDEBAR_ITEMS;
+
+// Toast configuration
+export const TOAST_WIDTH = 40;
+export const TOAST_MARGIN = 1;
+export const TOAST_DEFAULT_DURATION = 3000;
+export const TOAST_MAX_COUNT = 3;

package/src/controllers/app-controller.ts

@@ -0,0 +1,180 @@
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+import { SIDEBAR_ITEMS } from "../constants";
+import type { ConfirmDialog } from "../layout/confirm-dialog";
+import type { ContentWindow } from "../layout/content-window";
+import type { Sidebar } from "../layout/sidebar";
+import type { ToastManager } from "../layout/toast-manager";
+import type { Store } from "../store";
+import { filterTorrents } from "../utils/filter";
+
+type FocusMode = "global" | "dialog";
+type FocusArea = "sidebar" | "table";
+
+export class AppController {
+	private renderer: CliRenderer;
+	private store: Store;
+	private sidebar: Sidebar;
+	private contentWindow: ContentWindow;
+	private toastManager: ToastManager;
+	focusMode: FocusMode = "global";
+	focusArea: FocusArea = "sidebar";
+	private tableSelectedIndex = 0;
+	private pendingDeleteId: string | null = null;
+
+	// Injected by App after bridge/dialog are created
+	onAddTorrent?: () => void;
+	onQuit?: () => void;
+	onDialogClose?: () => void;
+	onDialogInput?: (key: string) => boolean;
+	onPauseTorrent?: (id: string) => void;
+	onResumeTorrent?: (id: string) => void;
+	onStartTorrent?: (id: string) => void;
+	onRemoveTorrent?: (id: string, deleteFiles: boolean) => void;
+
+	private _confirmDialog: ConfirmDialog | null = null;
+	set confirmDialog(dialog: ConfirmDialog) {
+		this._confirmDialog = dialog;
+		dialog.onConfirm = () => {
+			this.focusMode = "global";
+			if (this.pendingDeleteId) {
+				this.onRemoveTorrent?.(this.pendingDeleteId, true);
+				this.pendingDeleteId = null;
+			}
+		};
+		dialog.onCancel = () => {
+			this.focusMode = "global";
+			this.pendingDeleteId = null;
+		};
+	}
+
+	constructor(
+		renderer: CliRenderer,
+		store: Store,
+		sidebar: Sidebar,
+		contentWindow: ContentWindow,
+		toastManager: ToastManager,
+	) {
+		this.renderer = renderer;
+		this.store = store;
+		this.sidebar = sidebar;
+		this.contentWindow = contentWindow;
+		this.toastManager = toastManager;
+	}
+
+	start(): void {
+		this.store.subscribe((state) => {
+			const len = filterTorrents(state.torrents, state.selectedView).length;
+			if (len > 0 && this.tableSelectedIndex >= len) {
+				this.tableSelectedIndex = len - 1;
+			} else if (len === 0) {
+				this.tableSelectedIndex = 0;
+			}
+			this.sidebar.update(state, this.focusArea);
+			this.contentWindow.update(this.focusArea, this.tableSelectedIndex);
+		});
+
+		this.renderer.keyInput.on("keypress", (key) => {
+			this.handleKeyPress(key);
+		});
+
+		this.refreshView();
+	}
+
+	private refreshView(): void {
+		const state = this.store.getState();
+		this.sidebar.update(state, this.focusArea);
+		this.contentWindow.update(this.focusArea, this.tableSelectedIndex);
+	}
+
+	private getSelectedId(): string | null {
+		const state = this.store.getState();
+		return filterTorrents(state.torrents, state.selectedView)[this.tableSelectedIndex]?.id ?? null;
+	}
+
+	private handleKeyPress(key: KeyEvent): void {
+		if (this.focusMode === "dialog") {
+			if (this._confirmDialog?.getIsOpen()) {
+				this._confirmDialog.handleInput(key.name);
+			} else {
+				if (key.name === "escape") {
+					this.focusMode = "global";
+					this.onDialogClose?.();
+				} else {
+					this.onDialogInput?.(key.name);
+				}
+			}
+			return;
+		}
+
+		if (this.toastManager.handleInput(key.name)) {
+			return;
+		}
+
+		if (key.name === "tab") {
+			this.focusArea = this.focusArea === "sidebar" ? "table" : "sidebar";
+			this.refreshView();
+			return;
+		}
+
+		if (key.name === "j" || key.name === "down") {
+			if (this.focusArea === "sidebar") {
+				const total = SIDEBAR_ITEMS.status.length;
+				const state = this.store.getState();
+				const next = (state.selectedIndex + 1) % total;
+				this.store.setState({ selectedIndex: next, selectedView: SIDEBAR_ITEMS.status[next] ?? "All" });
+			} else {
+				const state = this.store.getState();
+				const len = filterTorrents(state.torrents, state.selectedView).length;
+				if (len > 0) {
+					this.tableSelectedIndex = Math.min(this.tableSelectedIndex + 1, len - 1);
+					this.refreshView();
+				}
+			}
+		} else if (key.name === "k" || key.name === "up") {
+			if (this.focusArea === "sidebar") {
+				const total = SIDEBAR_ITEMS.status.length;
+				const state = this.store.getState();
+				const prev = (state.selectedIndex - 1 + total) % total;
+				this.store.setState({ selectedIndex: prev, selectedView: SIDEBAR_ITEMS.status[prev] ?? "All" });
+			} else {
+				if (this.tableSelectedIndex > 0) {
+					this.tableSelectedIndex--;
+					this.refreshView();
+				}
+			}
+		} else if (key.name === "space") {
+			if (this.focusArea === "table") {
+				const id = this.getSelectedId();
+				if (!id) return;
+				const state = this.store.getState();
+				const torrent = filterTorrents(state.torrents, state.selectedView)[this.tableSelectedIndex];
+				if (!torrent) return;
+				if (torrent.status === "downloading") {
+					this.onPauseTorrent?.(id);
+				} else if (torrent.status === "paused") {
+					this.onResumeTorrent?.(id);
+				} else if (torrent.status === "stopped") {
+					this.onStartTorrent?.(id);
+				}
+			}
+		} else if (key.name === "d" && !key.shift) {
+			if (this.focusArea === "table") {
+				const id = this.getSelectedId();
+				if (id) this.onRemoveTorrent?.(id, false);
+			}
+		} else if (key.name === "d" && key.shift) {
+			if (this.focusArea === "table") {
+				const id = this.getSelectedId();
+				if (!id) return;
+				this.pendingDeleteId = id;
+				this.focusMode = "dialog";
+				this._confirmDialog?.open("Delete torrent and files?");
+			}
+		} else if (key.name === "a") {
+			this.focusMode = "dialog";
+			this.onAddTorrent?.();
+		} else if (key.name === "q") {
+			this.onQuit?.();
+		}
+	}
+}