From b61186921804c1629992c84f9c011ddadcdee985 Mon Sep 17 00:00:00 2001 From: nimbold <11913706+nimbold@users.noreply.github.com> Date: Mon, 1 Jun 2026 06:03:04 +0330 Subject: [PATCH] docs: simplify and restructure README to GitHub standards --- README.md | 153 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 78 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 2c557e4..843e137 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,100 @@ -# Firelink +
+

Firelink

+

A clean, native SwiftUI download manager for Apple Silicon macOS

-Firelink is a clean SwiftUI download manager for Apple Silicon Macs. The goal is to bring the practical parts of IDM/FDM-style download management to macOS with a native interface, segmented downloads, queue control, automatic file organization, and credential-aware transfers. + [![Swift Version](https://img.shields.io/badge/Swift-6.0-orange?logo=swift&logoColor=white)](https://swift.org) + [![Platform Support](https://img.shields.io/badge/macOS-14.0%2B-blue?logo=apple&logoColor=white)](https://apple.com) + [![Engine](https://img.shields.io/badge/Engine-aria2c-red?logo=terminal&logoColor=white)](https://aria2.github.io/) + [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE) +
-This project is early, but it already has a working native prototype, an `aria2c`-backed download engine, a queue-focused UI, batch link intake, and app-wide settings. +--- -## Features +**Firelink** brings the efficiency of multi-segmented download managers (like IDM or FDM) to macOS with a modern, native SwiftUI interface. Designed specifically for Apple Silicon, it delivers high-speed concurrent transfers, drag-and-drop queue control, automated file organization, and Keychain-secured authentication—all in a lightweight native package. -- Native SwiftUI macOS interface. -- Segmented downloads with a per-file connection count that also controls the split count. -- Multiple files downloading at the same time. -- Queue-based downloads with drag-and-drop priority ordering. -- Batch Add Downloads window for pasting one or many links at once. -- Automatic link parsing from newlines, whitespace, and common separators. -- Metadata preview for new downloads, including file size when the server reports it. -- Total required disk space and available disk space summary before adding downloads. -- Per-batch save location override, while keeping automatic file-type folders by default. -- Native macOS Settings window, available from App menu > Settings and the main toolbar. -- Configurable default per-server connection count. -- Configurable parallel file download limit in Settings. -- Per-batch connection controls in the Add Downloads window. -- Sidebar filters for all downloads, queued, active, completed, failed, and file categories. -- Sortable, resizable download table columns with a right-click column chooser. -- Default table columns for file name, size, progress/status, ETA, last try date, and date added. -- Download row context menu with properties, show in Finder, resume, stop, queue, and delete actions. -- Download properties window for editing URL, file name, save location, connection count, and login behavior. -- Delete confirmation with optional move-to-Trash for downloaded or partial files. -- Automatic cleanup of unfinished `.aria2` cache files when removing incomplete downloads. -- Automatic save folders under `~/Downloads`: - - `Musics` - - `Movies` - - `Compressed` - - `Pictures` - - `Documents` - - `Other` -- Custom download locations per file category. -- Broad file extension detection for audio, video, archive, image, and document formats. -- HTTP, HTTPS, FTP, and SFTP URL support through `aria2c`. -- Site login rules with URL pattern matching and Keychain-stored passwords. -- Optional prevention of system sleep while files are downloading, while still allowing display sleep. -- Pause, resume, cancel, delete, progress, speed, ETA, and connection count display. -- Release `.app` bundle script for local macOS builds. +--- -## Engine +## ✨ Key Features -This first version uses `aria2c` as the download engine. It is a better fit than plain `curl` for the requested IDM/FDM-style behavior because it has segmented downloads, resumable transfers, concurrent downloads, HTTP/FTP/SFTP support, and username/password options built in. +- ⚡ **High-Speed Downloads:** Multi-segmented download engine powered by `aria2c` for concurrent connections and optimal bandwidth utilization. Supports HTTP, HTTPS, FTP, and SFTP. +- 🎨 **Native macOS & SwiftUI:** Responsive interface designed natively for Apple Silicon, featuring resizable tables, customizable columns, sidebar filters, and a native Settings panel. +- 🗂️ **Smart Queue & Categories:** Drag-and-drop priority ordering, batch link ingestion with smart parsing, and automatic file organization (`Musics`, `Movies`, `Compressed`, `Pictures`, `Documents`, `Other`) based on extension detection. +- 🔒 **Keychain Security:** Local macOS Keychain integration for secure site credential storage and matching during transfers. +- ⚙️ **Power & System Integrity:** Optional system sleep prevention during active downloads, disk-space safety checks, and automated cleanup of partial `.aria2` metadata cache files. -Firelink uses one per-file connection value for both `aria2c` split count and same-server connection count. That keeps the download behavior close to the familiar IDM-style model: choosing 8 connections splits the file into 8 parallel segments. +
+🔍 View Full Feature Index (30+ features) -## Requirements +### All native SwiftUI macOS features: -Install the engine: +- **Core Download Engine:** + - Segmented downloads with per-file connection/split counts. + - Multi-threaded, parallel downloading with configurable limits. + - Support for HTTP, HTTPS, FTP, and SFTP transfers via `aria2c`. +- **Advanced Queue Control:** + - Drag-and-drop download reordering to manage priorities. + - Comprehensive download table with resizable, custom columns (Name, Size, Status, ETA, Dates). + - Individual download controls: pause, resume, stop, and queue actions. +- **Smart Link Ingestion:** + - Batch Add window for pasting multiple links at once. + - Automated link parsing (whitespaces, newlines, standard separators). + - Disk space availability checks and total size calculation prior to adding. +- **File Organization:** + - Automatic categorization of files (Music, Movies, Compressed, Documents, Images) into structured subfolders under `~/Downloads`. + - Smart fallback to customizable download folders per category. + - Automatic cleanup of unfinished `.aria2` metadata/cache files on removal. +- **Security & System:** + - Local macOS Keychain integration for site logins. + - Prevents system sleep while active transfers are in progress, preserving display sleep. + - Release `.app` bundle build scripts ready for distribution. -```sh +
+ +--- + +## ⚙️ Engine Architecture + +Firelink leverages `aria2c` under the hood as its core download engine. Unlike standard `curl`, `aria2c` allows: +- **Segmented Downloads:** Splits files into multiple streams for maximum transfer speeds. +- **Unified Connection Control:** A single slider regulates both the server connection count and segment split count, matching the intuitive behavior of classic managers like IDM/FDM. +- **Built-in Resumability:** Seamlessly resumes interrupted or paused downloads without data corruption. + +--- + +## 🛠️ Requirements & Setup + +### 1. Install Dependencies +Ensure you have **Homebrew** and the **Swift toolchain** installed: +```bash brew install aria2 ``` +- **OS Support:** macOS 14.0 or newer (built natively for Apple Silicon) +- **Toolchain:** Xcode 15+ / Swift 6.0 toolchain -- macOS 14 or newer. -- Apple Silicon Mac. -- Swift 6 toolchain. -- `aria2c` installed with Homebrew, or bundled into the app resources later. - -## Run - -```sh +### 2. Build & Run +Run the application directly via the terminal: +```bash swift run Firelink ``` -Build a release `.app` bundle: - -```sh -make app -open build/Firelink.app +Or build a production `.app` bundle: +```bash +make app && open build/Firelink.app ``` -Because the current machine only has Command Line Tools selected, this repository is set up as a Swift Package with a bundling script rather than a generated Xcode project. Opening the package in Xcode will still give you a native macOS app workflow. +--- -## Roadmap +## 🗺️ Roadmap -- Persist download history, queue order, column choices, and active download state across launches. -- Bundle or manage `aria2c` automatically so users do not need a separate Homebrew install. -- Add first-class pause/resume semantics with clearer partial-file and cache handling. -- Add per-download and global speed limits, plus scheduler rules for start/stop windows. -- Add retry policies, mirror fallback, and richer failure recovery for unstable servers. -- Add browser integration or a companion extension for capturing download links from Safari/Chrome/Firefox. -- Add cookie/header support for authenticated downloads that require browser sessions. -- Improve site-login editing, credential migration, and matching diagnostics. -- Add duplicate detection for URLs, file names, and already-downloaded files. -- Add checksum/hash verification and optional post-download integrity checks. -- Add download history search, saved filters, and better category management. -- Add signed/notarized release builds, auto-update support, and downloadable GitHub releases. -- Add localization-ready strings and accessibility review for keyboard and VoiceOver workflows. -- Add unit and integration tests for file classification, URL parsing, queue behavior, settings persistence, `aria2c` progress parsing, and metadata fetching. +- [ ] **Data Persistence:** Store history, column layout preferences, and active queues across restarts. +- [ ] **Zero-Config Setup:** Automatically bundle and configure `aria2c` inside the `.app` bundle. +- [ ] **Bandwidth Limits:** Add global and per-download speed caps and calendar schedules. +- [ ] **Browser Extensions:** Capture links directly from Safari, Chrome, and Firefox. +- [ ] **Advanced Transfer Features:** Checksum validation, cookie/header ingestion, and smart mirror failovers. +- [ ] **Distribution:** Notarized release builds, automated Sparkle updates, and Homebrew formulae. -## License +--- -Firelink is released under the MIT License. See [LICENSE](LICENSE). +## 📄 License + +Firelink is released under the MIT License. See [LICENSE](LICENSE) for details.