From 5b29784c07d532781b82e8a23cb9fdd19ed7d202 Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Sun, 23 Aug 2026 23:49:37 -0700 Subject: [PATCH] Adds comprehensive documentation. --- README.md | 123 ++++++++++++++++++++++++++---------------- Tasks.md | 14 ++--- docs/architecture.md | 92 +++++++++++++++++++++++++++++++ docs/gui-guide.md | 51 ++++++++++++++++++ docs/installation.md | 77 ++++++++++++++++++++++++++ docs/multi-account.md | 92 +++++++++++++++++++++++++++++++ 6 files changed, 397 insertions(+), 52 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/gui-guide.md create mode 100644 docs/installation.md create mode 100644 docs/multi-account.md diff --git a/README.md b/README.md index 0ba20ee..49e09ce 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,101 @@ # Nextcloud Upload Tool (`nut`) +[![CI](https://github.com/majinnaibu/nextcloud-upload-tool/actions/workflows/ci.yml/badge.svg)](https://github.com/majinnaibu/nextcloud-upload-tool/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) + A fast, cross-platform CLI tool and desktop GUI application for uploading files to Nextcloud and instantly generating direct download / public share links. --- -## Overview +## Key Features -**Nextcloud Upload Tool** is designed for quick terminal workflows and smooth desktop integration. It allows you to pipe or upload files directly to your Nextcloud instance, securely manage credentials via your OS keychain, and immediately copy shareable links. - -### Key Features - -- ⚡ **High-Performance Uploads**: WebDAV streaming uploads with real-time progress reporting and pipe support (`stdin`, `pv`). -- 🔗 **Instant Share Links**: Direct integration with Nextcloud's OCS Sharing API to generate public share URLs and direct-download links. +- ⚡ **High-Performance Uploads**: WebDAV streaming uploads with real-time progress reporting and pipe support (`stdin`, `pv`, Unix pipelines). +- 🔗 **Instant Share Links**: Direct integration with Nextcloud's OCS Sharing API to generate public share URLs and direct-download links with optional password protection. - 🔐 **Secure Credential Storage**: Native OS Keychain integration (macOS Keychain, Windows Credential Manager, Linux Secret Service) with encrypted file fallback. -- 👥 **Multi-Account Support**: Configure and switch between multiple Nextcloud accounts or self-hosted instances seamlessly. -- 🖥️ **CLI & GUI Frontends**: A lightweight terminal binary (`nut`) and a modern desktop application powered by Tauri. +- 👥 **Multi-Account Support**: Configure and switch between multiple Nextcloud accounts or self-hosted instances seamlessly across CLI and GUI. +- 🖥️ **Modern Desktop GUI**: Drag-and-drop queue management, per-file & total progress bars, retry handling, and browser-based Login Flow v2. +- 🤖 **Automation Ready**: Output formatting options (`--json`, `--tsv`, `--url-only`, `--direct-url-only`) and headless SSH / CI authentication. + +--- + +## Documentation + +- 📦 **[Installation Guide](docs/installation.md)**: Pre-built binaries, packages (`.dmg`, `.deb`, `.rpm`, `.msi`, `.AppImage`), and source compilation instructions. +- 🖥️ **[GUI User Guide](docs/gui-guide.md)**: Walkthrough of the desktop app, drag-and-drop queue, retry mechanics, and account management. +- 👥 **[Multi-Account Guide](docs/multi-account.md)**: Managing multiple servers, switching active defaults, and CLI/GUI token sharing. +- 🏗️ **[Architecture & Developer Guide](docs/architecture.md)**: Workspace layout, WebDAV/OCS protocol implementation, and Tauri IPC bridge. + +--- + +## Quick Start + +### 1. CLI Usage + +#### Connect your Nextcloud account: +```bash +# Interactive Login Flow v2 (opens browser): +nut login https://cloud.example.com --label "Work" + +# Or connect interactively via terminal prompt: +nut login https://cloud.example.com --manual + +# Or non-interactive / automated script: +nut login https://cloud.example.com -u alice -p "app-password" +``` + +#### Upload files and generate share links: +```bash +# Upload a single file and generate a public share link: +nut upload -s document.pdf + +# Upload multiple files into a remote folder: +nut upload -s -d "Projects/2026" file1.png file2.png + +# Upload recursively: +nut upload -s -r assets/ + +# Stream from standard input (e.g. backup pipes): +tar -czf - data/ | nut upload -s --stdin --filename "backup.tar.gz" + +# Output only the share link (ideal for scripts and clipboard pipes): +nut upload -s --url-only report.pdf | pbcopy +``` + +#### Manage multiple accounts: +```bash +# List all accounts: +nut accounts + +# Switch default active account: +nut account default "Work" + +# Upload to a specific account: +nut upload --account "Personal" photo.jpg +``` + +--- + +### 2. GUI Usage + +Launch the desktop app via `nut-gui` or from your system applications menu. Drag and drop any files into the window, configure your remote destination folder, toggle public share link creation, and click **Upload All**. --- ## Project Structure -This repository is structured as a Cargo workspace: - ``` . -├── nextcloud_client/ # Core Rust backend library (WebDAV, OCS API, Keyring, Config) -├── cli/ # Terminal CLI executable (`nut`) -├── gui/ # Desktop GUI application (Tauri + Web frontend) -├── Tasks.md # Canonical project roadmap and task tracking +├── nextcloud_client/ # Core Rust backend library (WebDAV, OCS API, Keyring, Config) +├── cli/ # Terminal CLI executable (`nut`) +├── gui/ # Desktop GUI application (Tauri v2 + React frontend) +├── docs/ # Detailed guides and developer documentation +├── scripts/ # Packaging and build helper scripts +├── Tasks.md # Canonical project roadmap and task tracking └── README.md ``` --- -## Getting Started - -### Prerequisites - -- [Rust](https://www.rust-lang.org/) (1.75+ recommended) -- A running [Nextcloud](https://nextcloud.com/) instance with WebDAV and sharing enabled - -### Building the Workspace - -Clone the repository and build the workspace crates: - -```bash -# Build all workspace members -cargo build - -# Run the CLI tool -cargo run -p nut -- --help - -# Run tests -cargo test --workspace -``` - ---- - -## Roadmap & Tasks - -Project tasks, feature specifications, and current progress are tracked in [Tasks.md](Tasks.md). - ---- - ## License This project is licensed under the [MIT License](LICENSE). diff --git a/Tasks.md b/Tasks.md index f704f12..6419506 100644 --- a/Tasks.md +++ b/Tasks.md @@ -71,7 +71,6 @@ This document defines the complete project roadmap and task tracking system for | ID | Title | Status | Type | |---|---|---|---| | [NUT-019](#nut-019) | Implement Homebrew/Winget/Chocolatey Manifests | Triage | Chore | -| [NUT-020](#nut-020) | Write Documentation + Examples | Triage | Chore | | [NUT-022](#nut-022) | Implement CLI Shell Completions Generation | Triage | Feature | | [NUT-023](#nut-023) | Write Comprehensive CLI Documentation and Automation Guides | Triage | Chore | | [NUT-024](#nut-024) | Create Docker/Podman Nextcloud Integration Test Harness | Triage | Foundation | @@ -93,6 +92,7 @@ This document defines the complete project roadmap and task tracking system for | [NUT-016](#nut-016) | Implement Shared Auth Token Reuse | Fixed | Integration | | [NUT-017](#nut-017) | Implement Multi-Account Switching (GUI + CLI) | Fixed | Integration | | [NUT-018](#nut-018) | Implement Packaging for macOS, Windows, Linux | Fixed | Chore | +| [NUT-020](#nut-020) | Write Documentation + Examples | Fixed | Chore | | [NUT-021](#nut-021) | Support Headless & SSH Remote Authentication Modes | Fixed | Feature | --- @@ -481,20 +481,20 @@ Add package manager manifests for easy installation. - NUT-018 - + ### Write Documentation + Examples **ID:** NUT-020 -**Status:** Triage +**Status:** Fixed **Type:** Chore **Description:** Write comprehensive project documentation covering installation, GUI usage, multi-account setup, and overall project architecture. **Requirements:** -- [ ] GUI overview and visual walkthrough -- [ ] Cross-platform installation instructions -- [ ] Multi-account management guide -- [ ] Architecture and developer setup documentation +- [x] GUI overview and visual walkthrough +- [x] Cross-platform installation instructions +- [x] Multi-account management guide +- [x] Architecture and developer setup documentation **Dependencies:** - NUT-012 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..f2fc8ff --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,92 @@ +# Project Architecture & Developer Setup + +This document describes the architectural layout, internal protocols, security model, and developer setup for the **Nextcloud Upload Tool**. + +--- + +## 1. Workspace Layout + +The repository is organized as a Cargo workspace with three primary crates: + +``` +nextcloud-upload-tool/ +├── nextcloud_client/ # Shared Rust core library +│ ├── src/ +│ │ ├── auth.rs # Nextcloud Login Flow v2 client & polling +│ │ ├── client.rs # NextcloudClient WebDAV client & status checks +│ │ ├── config.rs # ClientConfig and URL normalization +│ │ ├── credentials.rs # CredentialStore (OS Keychain + accounts.json) +│ │ ├── download.rs # Direct-download URL generator +│ │ ├── progress.rs # Async ProgressStream & progress callbacks +│ │ └── sharing.rs # OCS Sharing API (public share link creation) +├── cli/ # CLI binary (`nut`) +│ └── src/ +│ └── main.rs # Clap CLI parser, upload handlers, terminal output +├── gui/ # Desktop application (Tauri v2 + React) +│ ├── src/ # React + TypeScript frontend +│ │ ├── App.tsx # UI tabs, drag-and-drop, state management +│ │ └── App.css # Styling and responsive layout +│ └── src-tauri/ # Tauri Rust backend +│ ├── src/commands.rs # IPC command handlers forwarding to nextcloud_client +│ └── tauri.conf.json # Multi-platform bundle configuration +└── docs/ # Documentation & user guides +``` + +--- + +## 2. Shared Core Architecture (`nextcloud_client`) + +Both the CLI and GUI frontends share the `nextcloud_client` crate to ensure consistent behavior: + +- **WebDAV Upload Pipeline**: + - Implements HTTP PUT requests against Nextcloud's WebDAV endpoint (`/remote.php/dav/files//`). + - Employs streaming request bodies wrapped in a custom `ProgressStream` to capture transferred byte counts in real time without buffering large files in RAM. + - Automatically handles intermediate remote directory resolution. + +- **OCS Sharing API**: + - Interacts with `/ocs/v2.php/apps/files_sharing/api/v1/shares` using OCS headers (`OCS-APIRequest: true`). + - Creates public read-only shares (`shareType=3`, `permissions=1`) with optional password protection. + - Generates canonical public share links (`/index.php/s/`) and direct download links (`/index.php/s//download`). + +- **Unified Credential Storage**: + - **Keyring Service**: Keyring service identifier `me.majinnaibu.nut`. + - **Account Metadata**: Stored in `~/.config/nut/accounts.json` containing account IDs, server URLs, usernames, labels, and default account flags. + - **Secrets**: App passwords and tokens are stored in the OS native keychain (Apple Keychain on macOS, Windows Credential Manager on Windows, and Secret Service on Linux). + +--- + +## 3. GUI Architecture & IPC Bridge + +The GUI is built with **Tauri v2** using a lightweight React frontend: +- **Tauri Commands**: Defined in `gui/src-tauri/src/commands.rs` exposing async Rust functions (`upload_file`, `get_accounts`, `login_v2_start`, `login_v2_poll`, `set_default_account`, etc.) to TypeScript. +- **Event Streaming**: As WebDAV uploads progress, the Rust backend emits `upload-progress` events to the Tauri webview containing `file_id`, `bytes_transferred`, `total_bytes`, and `percent`. +- **Drag-and-Drop Integration**: The native OS drag-and-drop listener intercepts dropped files and invokes `get_file_info` to populate the upload queue. + +--- + +## 4. Developer Setup & Testing + +### Running Tests +```bash +# Run all unit and integration tests across the workspace +cargo test --workspace + +# Run CLI tests only +cargo test -p nut + +# Run core library tests only +cargo test -p nextcloud_client +``` + +### Running GUI in Development Mode +```bash +# In terminal 1: start Vite dev server +cd gui +npm install +npm run dev + +# In terminal 2: run Tauri dev desktop app +cargo run -p gui +# Or use Tauri CLI +npm run tauri dev +``` diff --git a/docs/gui-guide.md b/docs/gui-guide.md new file mode 100644 index 0000000..0d68a20 --- /dev/null +++ b/docs/gui-guide.md @@ -0,0 +1,51 @@ +# GUI Desktop Application Guide + +The **Nextcloud Upload Tool GUI** is a fast desktop application designed for streamlined file queuing, drag-and-drop uploads, public share creation, and multi-account management. + +--- + +## 1. Interface Overview + +The interface is structured into three primary sections: + +1. **Header Bar**: + - Displays the application branding. + - **Account Switcher**: Quick-switch dropdown to select the target Nextcloud account for uploads. + - **Navigation Tabs**: Toggle between **Upload Queue** and **Accounts & Auth**. + +2. **Upload Queue Tab**: + - **Target Settings**: Configure remote directory on Nextcloud (default: `Uploads`), toggle public share generation, and set optional link passwords. + - **Drag & Drop Zone**: Visual target supporting OS file drops or manual system file browser selection (`Browse Files`). + - **Queue List**: Per-file upload queue showing status badges (`queued`, `uploading`, `completed`, `error`), live percentage, byte counters, and action buttons (`▲`, `▼`, `✕`, inline `↻ Retry`). + - **Global Actions**: `Upload All (N)` button and `Clear Completed` / `Clear All`. + +3. **Accounts & Auth Tab**: + - **Connected Accounts**: Interactive cards displaying connected usernames, server endpoints, custom labels, and active default status. + - **Browser Login (Login Flow v2)**: One-click interactive authorization opening your web browser with support for 2FA / SSO. + - **Manual App Password Entry**: Form for connecting with custom server URLs, usernames, and generated application tokens. + +--- + +## 2. Step-by-Step Walkthrough + +### Connecting Your First Account +1. Open the application and switch to the **Accounts & Auth** tab. +2. Enter your Nextcloud server URL (e.g. `https://cloud.example.com`). +3. Click **Authorize in Browser (Login Flow v2)**. +4. Your default browser opens the authorization page. Click **Grant Access**. +5. The GUI automatically polls and securely stores your token in your operating system's native keychain. + +### Uploading Files & Creating Share Links +1. Navigate to the **Upload Queue** tab. +2. Drag and drop one or more files from Finder / Explorer / File Manager into the dropzone. +3. (Optional) Check **Generate public share link** and specify a **Share password** if needed. +4. Set the **Remote Directory** (e.g. `Projects/Assets` or `Uploads`). +5. Click **Upload All**. +6. Real-time progress bars update for both the total batch and each individual file. +7. Once finished: + - Click **Copy Link** to copy the public share URL to clipboard. + - Click **Copy Direct Download** to copy the raw download URL. + +### Managing Failed Uploads +- If any file fails (e.g. due to network glitch or server quota), an error badge is displayed with details. +- Click the inline **↻ Retry** button next to that item to re-attempt the upload immediately without resetting the queue. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..dc12790 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,77 @@ +# Installation Guide + +**Nextcloud Upload Tool (`nut`)** is available as a standalone command-line tool and a desktop GUI application across macOS, Windows, and Linux. + +--- + +## 1. Pre-built Binaries & Installers + +Download pre-built releases for your operating system from the [Releases](https://github.com/majinnaibu/nextcloud-upload-tool/releases) page. + +### macOS (Apple Silicon & Intel) +- **GUI Desktop App**: Download the `.dmg` installer, open it, and drag `Nextcloud Upload Tool.app` into `/Applications`. +- **CLI Binary**: + ```bash + # Apple Silicon (M1/M2/M3/M4) + curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-aarch64-apple-darwin.tar.gz | tar -xz + sudo mv nut /usr/local/bin/ + + # Intel x86_64 + curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-x86_64-apple-darwin.tar.gz | tar -xz + sudo mv nut /usr/local/bin/ + ``` + +### Linux (Debian, Ubuntu, Fedora, Arch, Generic) +- **Debian / Ubuntu (`.deb`)**: + ```bash + sudo dpkg -i nextcloud-upload-tool_0.1.0_amd64.deb + sudo apt-get install -f + ``` +- **Fedora / RHEL (`.rpm`)**: + ```bash + sudo rpm -i nextcloud-upload-tool-0.1.0-1.x86_64.rpm + ``` +- **Universal AppImage**: + ```bash + chmod +x Nextcloud_Upload_Tool_0.1.0_amd64.AppImage + ./Nextcloud_Upload_Tool_0.1.0_amd64.AppImage + ``` +- **Static CLI Binary (musl libc - zero external dependencies)**: + ```bash + curl -fsSL https://github.com/majinnaibu/nextcloud-upload-tool/releases/latest/download/nut-x86_64-unknown-linux-musl.tar.gz | tar -xz + sudo mv nut /usr/local/bin/ + ``` + +### Windows +- **GUI Installer (`.msi` / NSIS `.exe`)**: Download and run `Nextcloud-Upload-Tool-Setup.exe` or `Nextcloud-Upload-Tool.msi`. Follow the installer wizard. +- **Standalone CLI**: Download `nut-x86_64-pc-windows-msvc.zip`, extract `nut.exe`, and add it to your system `%PATH%`. + +--- + +## 2. Building from Source + +### Prerequisites +- **Rust toolchain** (1.75+): Install via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` +- **Node.js** (v20+) and **npm** (for GUI frontend build) +- **Platform Development Libraries**: + - **Linux**: `sudo apt-get install libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev libssl-dev patchelf` + - **macOS**: Xcode Command Line Tools (`xcode-select --install`) + - **Windows**: Visual Studio C++ Build Tools + +### Build the CLI (`nut`) +```bash +git clone https://github.com/majinnaibu/nextcloud-upload-tool.git +cd nextcloud-upload-tool + +cargo build --release -p nut +# The binary is placed at target/release/nut +``` + +### Build the Desktop GUI +```bash +cd gui +npm install +npm run build +npm run tauri build +# The packaged bundle is located in gui/src-tauri/target/release/bundle/ +``` diff --git a/docs/multi-account.md b/docs/multi-account.md new file mode 100644 index 0000000..cab6e48 --- /dev/null +++ b/docs/multi-account.md @@ -0,0 +1,92 @@ +# Multi-Account Management Guide + +**Nextcloud Upload Tool** supports managing multiple Nextcloud instances and user accounts simultaneously. Credentials, account metadata, and active default states are shared seamlessly between the CLI and GUI frontends. + +--- + +## 1. How Accounts Are Identified + +Every configured account has a canonical ID in the format: +``` +username@host +``` +*(e.g. `alice@cloud.example.com` or `dev@nextcloud.local`)* + +You can also assign an optional friendly **label** (e.g. `"Work"`, `"Personal"`, `"Backup"`). + +--- + +## 2. Managing Accounts via CLI (`nut`) + +### Listing Configured Accounts +```bash +nut accounts +# or +nut account list +``` +Outputs: +```text +Configured Nextcloud Accounts: + + • alice@cloud.example.com * (active default) + Username: alice + Server: https://cloud.example.com + Label: Work + + • bob@nextcloud.org + Username: bob + Server: https://nextcloud.org + Label: Personal +``` + +To output as JSON or TSV for scripting: +```bash +nut accounts --json +nut accounts --tsv +``` + +### Adding an Account +- **Interactive Browser Flow**: + ```bash + nut login https://cloud.example.com --label "Work" + ``` +- **Interactive Terminal Password Prompt**: + ```bash + nut login https://cloud.example.com --manual --label "Work" + ``` +- **Non-Interactive / Headless / Scripting**: + ```bash + nut login https://cloud.example.com -u alice -p "app-password-token" --label "Work" + ``` + +### Switching the Active Default Account +```bash +# Set default by label +nut account default Work + +# Or set default by full account ID +nut account default alice@cloud.example.com +``` + +### Uploading to a Specific Account +Use the `--account` / `-a` flag on any upload command to override the active default for that invocation: +```bash +nut upload --account "Work" report.pdf +nut upload --account "bob@nextcloud.org" archive.zip +``` + +### Removing an Account +```bash +nut account delete "Work" +``` +This removes the account from `~/.config/nut/accounts.json` and deletes the associated app token from your OS keychain. + +--- + +## 3. Managing Accounts in the GUI + +1. Open the **Accounts & Auth** tab. +2. The list of connected accounts displays each account's server URL, username, label, and whether it is marked as default. +3. Click **Set as Default** on any account card to switch the primary default. +4. Click **Select as Active** to switch the current session's upload destination. +5. Click **Logout / Remove** to purge credentials from the OS keychain.