| project |
|
|||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| task-statuses |
|
|||||||||||||||||||||||||||||||||||||||||||||
| task-types |
|
This document defines the complete project roadmap and task tracking system for the Nextcloud Upload Tool, encompassing the CLI and GUI applications, shared backend library, credential storage, and distribution packaging.
Important
For Agents & Contributors:
- Anchor Tags as SSOT: The HTML anchor tag
<a id="..." class="task" data-status="..." data-task-type="..."></a>above each task heading is the single source of truth (SSOT) for ID, status, and task type. - Task Details as SSOT: The detailed task body is the SSOT for title, description, requirements checklist, and direct dependencies.
- Rendered Sections: The Tasks Summary table and the bottom enum tables (Task Statuses & Task Types) are rendered views that must be synchronized whenever SSOT data changes.
- Single Task Scope: Implement only one task at a time, test and verify, update Tasks.md, and pause for user commit.
- Full Documentation: Review the complete rules, schemas, and contributor workflows in Task System Documentation & Rules and AGENTS.md before editing or restructuring tasks.
| ID | Title | Status | Type |
|---|---|---|---|
| NUT-001 | Establish Repository Structure | Done | Foundation |
| NUT-002 | Implement Shared Rust Backend Library | Done | Foundation |
| NUT-003 | Implement WebDAV Upload Logic | Done | Feature |
| NUT-004 | Implement OCS Share Link Generation | Done | Feature |
| NUT-005 | Implement Direct Download URL Builder | Done | Feature |
| NUT-006 | Implement Credential Storage System | Done | Feature |
| NUT-007 | Implement Multi-Account Support (Backend) | Done | Feature |
| NUT-008 | Implement CLI Frontend | Done | Feature |
| NUT-009 | Implement CLI Output Formatting Options | Done | Feature |
| NUT-010 | Implement CLI Multi-file Upload Support | Done | Feature |
| NUT-011 | Implement CLI Progress Reporting + pv Support | Done | Feature |
| NUT-012 | Implement GUI (Tauri) Frontend | Done | Feature |
| NUT-013 | Implement GUI File Queue + Drag-and-Drop | Done | Feature |
| NUT-014 | Implement GUI Credential Management UI | Done | Feature |
| NUT-015 | Implement GUI Upload Progress Bars | Done | Feature |
| NUT-016 | Implement Shared Auth Token Reuse | Done | Integration |
| NUT-017 | Implement Multi-Account Switching (GUI + CLI) | Done | Integration |
| NUT-018 | Implement Packaging for macOS, Windows, Linux | Done | Chore |
| NUT-019 | Implement Homebrew/Winget/Chocolatey Manifests | Done | Chore |
| NUT-020 | Write Documentation + Examples | Done | Chore |
| NUT-021 | Support Headless & SSH Remote Authentication Modes | Done | Feature |
| NUT-022 | Implement CLI Shell Completions Generation | Done | Feature |
| NUT-023 | Write Comprehensive CLI Documentation and Automation Guides | Done | Chore |
| NUT-024 | Create Docker/Podman Nextcloud Integration Test Harness | Done | Foundation |
| NUT-025 | Optimize CI Workflow with Fast-Forward Commit Reuse and Git Notes Metadata | Done | Chore |
| NUT-026 | Build React Documentation & Marketing Website on GitHub Pages | Done | Feature |
| NUT-027 | Configure GitHub Pages Deployment Workflow on develop Branch Updates | Done | Chore |
ID: NUT-001
Status: Done
Type: Foundation
Description:
Create the initial repository layout for the project, including the shared Rust backend library, CLI tool, and Tauri GUI application. This establishes the monorepo structure and build configuration.
Requirements:
- Create root-level Cargo workspace
- Create
nextcloud_client/Rust crate - Create
cli/Rust crate - Create
gui/Tauri project - Add
.editorconfigand.gitignore - Add README with project overview
Dependencies:
None
ID: NUT-002
Status: Done
Type: Foundation
Description:
Implement the shared Rust library that provides all core functionality: WebDAV upload, OCS share creation, credential storage, and progress callbacks. This library is used by both the CLI and GUI.
Requirements:
- Create
NextcloudClientstruct - Implement async runtime setup
- Define error types
- Define configuration structs
- Provide high-level API for upload + share
Dependencies:
- NUT-001
ID: NUT-003
Status: Done
Type: Feature
Description:
Implement file upload using Nextcloud’s WebDAV API. Support streaming uploads, file size detection, and progress callbacks.
Requirements:
- Implement PUT request to WebDAV endpoint
- Support streaming from file or stdin
- Provide progress callback API
- Handle authentication
Dependencies:
- NUT-002
ID: NUT-004
Status: Done
Type: Feature
Description:
Implement creation of public share links using the OCS Sharing API.
Requirements:
- POST to
/ocs/v2.php/apps/files_sharing/api/v1/shares - Parse JSON/XML response
- Extract share token
- Return share metadata
Dependencies:
- NUT-002
ID: NUT-005
Status: Done
Type: Feature
Description:
Generate direct-download URLs from share tokens.
Requirements:
- Build URL:
/index.php/s/<token>/download - Validate token format
- Provide helper API
Dependencies:
- NUT-004
ID: NUT-006
Status: Done
Type: Feature
Description:
Implement secure credential storage using OS keychain when available, falling back to encrypted config files. Support Nextcloud Login Flow v2 (/index.php/login/v2) for browser-based interactive authentication (supporting 2FA/SSO) alongside manual app password entry.
Requirements:
- Implement Nextcloud Login Flow v2 client (initiate + browser open + polling)
- macOS Keychain support
- Windows Credential Manager support
- Linux Secret Service support
- Encrypted fallback file
- Store server URL, username, app password
Dependencies:
- NUT-002
ID: NUT-007
Status: Done
Type: Feature
Description:
Support multiple Nextcloud accounts in the backend credential system.
Requirements:
- Add account list structure
- Add default account selection
- Add account switching API
Dependencies:
- NUT-006
ID: NUT-008
Status: Done
Type: Feature
Description:
Implement the CLI tool using the shared backend library, including interactive browser login via Login Flow v2 and file upload commands.
Requirements:
- Add
logincommand (browser-based Login Flow v2) - Add
uploadcommand - Add
--accountflag - Add
--stdinsupport - Add error reporting
Dependencies:
- NUT-003
- NUT-004
- NUT-005
- NUT-006
ID: NUT-009
Status: Done
Type: Feature
Description:
Add output formatting options for scripting and automation.
Requirements:
- JSON output (
--json) - TSV output (
--tsv) - Flags for path/filename/url (
--url-only,--direct-url-only) - Quiet mode (
--quiet/-q)
Dependencies:
- NUT-008
ID: NUT-010
Status: Done
Type: Feature
Description:
Support uploading multiple files in a single CLI invocation, including recursive directory uploading, glob expansions, batch progress summaries, and --continue-on-error.
Requirements:
- Accept multiple file paths and globs
- Recursive directory upload support (
--recursive/-r) - Continue on error option (
--continue-on-error/-c) - Aggregate upload summary (count, total bytes, share links)
- JSON array and multi-row TSV output formatting for multi-file batches
Dependencies:
- NUT-008
- NUT-009
ID: NUT-011
Status: Done
Type: Feature
Description:
Integrate rich progress reporting with indicatif (speed, ETA, byte counters), pipe-friendly detection (e.g. pv and headless/script pipes), and manual size hints for stdin streams.
Requirements:
- Detect file size & support
--sizehint for stdin streams - Rich terminal progress bar with speed (MB/s), ETA, bytes transferred, and percentage
- Auto-detect TTY: silence progress bars when piped to downstream tools or files
- Support explicit
--no-progressflag - Support piping directly from
pvor Unix pipelines without display conflicts
Dependencies:
- NUT-003
- NUT-008
ID: NUT-012
Status: Done
Type: Feature
Description:
Implement the Tauri-based GUI application with a clean, responsive layout connecting the React frontend to the shared Rust backend.
Requirements:
- Connect shared Rust backend library to Tauri commands in
gui/src-tauri - Implement responsive application layout with navigation & account indicator
- Implement file upload UI with destination path, public share link generation, and password protection
- Implement real-time feedback with share links, direct download URLs, and copy actions
Dependencies:
- NUT-002
- NUT-003
- NUT-004
- NUT-005
- NUT-006
ID: NUT-013
Status: Done
Type: Feature
Description:
Add drag-and-drop file support and a queue system for multiple uploads.
Requirements:
- Drag-and-drop area
- File queue list
- Remove/reorder items
Dependencies:
- NUT-012
ID: NUT-014
Status: Done
Type: Feature
Description:
Add UI for managing accounts, logging in (including one-click browser authorization via Login Flow v2), logging out, and switching accounts.
Requirements:
- Account list UI
- Browser-based login button (Login Flow v2)
- Manual login form (server/user/token)
- Logout button
- Switch account dropdown
Dependencies:
- NUT-007
- NUT-012
ID: NUT-015
Status: Done
Type: Feature
Description:
Add per-file and total progress bars to the GUI.
Requirements:
- Per-file progress
- Total progress
- Error display
Dependencies:
- NUT-003
- NUT-012
- NUT-013
ID: NUT-016
Status: Done
Type: Integration
Description:
Ensure both CLI and GUI reuse the same credential store and cached tokens.
Requirements:
- Shared credential backend
- Shared token cache
- Unified config format
Dependencies:
- NUT-006
- NUT-008
- NUT-012
ID: NUT-017
Status: Done
Type: Integration
Description:
Add multi-account switching to both CLI and GUI.
Requirements:
- CLI
--accountflag - GUI dropdown
- Shared backend logic
Dependencies:
- NUT-007
- NUT-008
- NUT-014
ID: NUT-018
Status: Done
Type: Chore
Description:
Package the CLI and GUI for distribution across macOS, Windows, and Linux.
Requirements:
- macOS
.app+.dmg - Windows
.exe+ installer - Linux
.deb+.rpm - Static CLI binaries
Dependencies:
- NUT-008
- NUT-012
ID: NUT-019
Status: Done
Type: Chore
Description:
Add package manager manifests for easy installation.
Requirements:
- Homebrew formula
- Winget manifest
- Chocolatey package
- AUR PKGBUILD
Dependencies:
- NUT-018
ID: NUT-020
Status: Done
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
Dependencies:
- NUT-012
- NUT-017
- NUT-018
ID: NUT-021
Status: Done
Type: Feature
Description:
Ensure smooth authentication experiences when running the CLI over SSH or in headless environments where a local graphical browser cannot be launched automatically.
Requirements:
- Terminal URL fallback: print clickable Login Flow v2 URL in terminal when browser fails to launch
- Add
--no-browserflag to print URL and wait for authorization without attempting to open desktop browser - Add interactive manual terminal prompt (
--manual) for username and app password input - Add non-interactive flag inputs (
--username,--app-password) for automated provisioning and CI/CD
Dependencies:
- NUT-006
- NUT-008
ID: NUT-022
Status: Done
Type: Feature
Description:
Add automated shell completion script generation using clap_complete for major shells (bash, zsh, fish, powershell, elvish).
Requirements:
- Add
clap_completecrate dependency - Implement
nut completions <SHELL>subcommand - Support
bash,zsh,fish,powershell, andelvishoutput to stdout - Include quick installation instructions in command help
Dependencies:
- NUT-008
ID: NUT-023
Status: Done
Type: Chore
Description:
Write dedicated CLI reference documentation and practical automation guides for scripting, CI/CD, and Unix pipeline workflows.
Requirements:
- Document all CLI subcommands (
login,upload,accounts,completions) and flags inREADME.md - Provide practical recipes for piping data (
stdin,pv,curl,mysqldump) - Provide scripting examples parsing
--json,--tsv,--url-only, and--direct-url-onlywithjqandxargs - Document headless SSH and CI/CD automated provisioning with
--usernameand--app-password
Dependencies:
- NUT-008
- NUT-009
- NUT-010
- NUT-011
- NUT-021
ID: NUT-024
Status: Done
Type: Foundation
Description:
Create a containerized integration test harness using Docker or Podman to spin up an ephemeral, fresh Nextcloud instance, seed an admin test account and credentials, and execute end-to-end integration tests for the CLI against real WebDAV and OCS sharing endpoints.
Requirements:
- Provide setup script (
scripts/test-server-up.sh) using Docker/Podman compose to launch and initialize a fresh Nextcloud container - Automatically configure admin user credentials, disable password expiration, and establish app password / token
- Provide teardown script (
scripts/test-server-down.sh) for clean container and volume disposal - Implement Rust integration test suite (
tests/cli_integration.rsorcli/tests/) running real CLI uploads, folder creations, stdin streams, and public share link verifications - Support automated CI/CD execution of the integration harness
Dependencies:
- NUT-008
- NUT-009
- NUT-010
- NUT-011
- NUT-021
ID: NUT-025
Status: Done
Type: Chore
Description:
Enhance the GitHub Actions CI workflow (.github/workflows/ci.yml) to build on pushes and pull requests to main, staging, and develop, avoid redundant rebuilds of fast-forward commits that have already passed CI, record per-OS check completion via GitHub Commit Statuses and Git Notes (refs/notes/ci), and expose a unified merge-check gate job for branch protection.
Requirements:
- Configure concurrency control in
.github/workflows/ci.ymlto cancel superseded PR runs - Resolve the true commit SHA (
pull_request.head.shaon PRs,github.shaon pushes) and verify fast-forward ancestry against the target base branch on PRs - Check existing GitHub Commit Statuses (
ci/<os>) and Git Notes (refs/notes/ci) before running heavy build/test steps so already-verified checks skip cleanly on fast-forward merges and flaky reruns - Record passed per-OS checks to both GitHub Commit Statuses (
ci/<os>) andrefs/notes/ci(with retry-safe atomic push) - Add a final
ci-gatejob suitable for GitHub Branch Protection required merge checks onmain,staging, anddevelop
Dependencies:
- NUT-001
ID: NUT-026
Status: Done
Type: Feature
Description:
Create a web/ project in the source tree for the project website hosted via GitHub Pages at https://headhunter45.github.io/NextcloudUploadTool. Standardize both gui/ and web/ on the same pinned Node.js version in root .nvmrc, Yarn Berry (via Corepack), React 19, TypeScript, Vite, and Tailwind CSS, and build a pure static SPA (no Jekyll) featuring marketing/presentation content, interactive examples, and comprehensive CLI/GUI documentation.
Requirements:
- Pin Node.js version in root
.nvmrcand migrategui/andweb/to Yarn Berry (nodeLinker: node-modules) with shared React 19, Vite, TypeScript, and Tailwind CSS tooling - Scaffold
web/React + Tailwind CSS project configured for GitHub Pages base path (/NextcloudUploadTool/) and URL (https://headhunter45.github.io/NextcloudUploadTool) - Capture screenshots and animated GIFs of the GUI application workflows (upload queue, drag-and-drop, progress bars, account management) and embed them in the website and documentation
- Create landing/marketing presentation page highlighting key CLI and GUI features, screenshots/GIF walkthroughs, and latest release download links and version metadata
- Integrate project documentation (
docs/cli-reference.md,docs/automation-recipes.md,docs/installation.md,docs/gui-guide.md,docs/multi-account.md,docs/architecture.md) and usage examples into the React site - Update CI/release scripts and workflows to use Yarn Berry for
gui/andweb/builds
Dependencies:
- NUT-018
- NUT-020
- NUT-023
ID: NUT-027
Status: Done
Type: Chore
Description:
Create a GitHub Actions GitHub Pages deployment workflow (modeled after OpenTasks's .github/workflows/deploy.yml, adapted from main to develop) that builds the web/ React + Tailwind application with Yarn Berry and deploys the compiled web/dist static bundle directly to https://headhunter45.github.io/NextcloudUploadTool (using GitHub Actions Pages deployment, without Jekyll) whenever develop is updated, on release tag pushes (v* excluding *-dev*), or via manual workflow_dispatch, ensuring the published site always references the latest release downloads and versions.
Requirements:
- Trigger GitHub Pages build and deployment on pushes to
develop, release tags (v*,!*-dev*), andworkflow_dispatch(with optionalversioninput) - Configure GitHub Pages workflow permissions (
contents: write,pages: write,id-token: write) and concurrency control (group: 'pages',cancel-in-progress: false) - Setup Node.js from root
.nvmrcwith Corepack / Yarn Berry enabled and resolve the latest published release version and download URLs (from GitHub Releases API / release tag / ancestorv*git tag) - Build
web/(yarn build) with the latest release version and asset download links injected into the React build and uploadweb/distviaactions/upload-pages-artifact@v3 - Deploy the uploaded artifact to the
github-pagesenvironment viaactions/deploy-pages@v4
Dependencies:
- NUT-026
This section defines how contributors and AI agents must interpret, update, and maintain this Tasks.md file.
- Task Anchor Tag: The HTML anchor tag directly above each task title is the SSOT for machine-readable attributes:
- Task ID:
idattribute (lowercase, e.g.id="nut-001") - Task Status:
data-statusattribute (must match a value intask-statusesfrontmatter) - Task Type:
data-task-typeattribute (must match a value intask-typesfrontmatter)
- Task ID:
- Detailed Task Section: The markdown text under the task heading is the SSOT for human-readable content:
- Task title (
### Title) - Task ID label (
**ID:** NUT-XXX) - Task status label (
**Status:** ...) - Task type label (
**Type:** ...) - Description, Requirements checklist (
- [ ] ...), and Dependencies.
- Task title (
- Rendered Sections: Tables marked as
(Rendered from ...)are non-canonical views generated from frontmatter and task anchor/detail sections.
Tasks progress through defined statuses:
triage: Under initial evaluation and specification. Missing requirements allowed.pending: Scope defined and ready for active work.in_progress: Active implementation in progress.done: Done. Work complete, requirements checked, and verified.blocked: Blocked by an external obstacle or unmet dependency.cancelled: Deprecated or abandoned.
- Task ID Schema:
${project.prefix}-XXXwhereXXXis a zero-padded monotonic 3-digit number (e.g.NUT-001). - IDs must be monotonic and never renumbered or reused.
- Anchor IDs are lowercase:
<a id="nut-001" class="task" data-status="pending" data-task-type="foundation"></a>. - Table and header IDs are uppercase:
[NUT-001](#nut-001). - Dependencies list direct dependencies only (no transitive dependencies).
- Checklists must use standard GitHub Markdown
- [ ]and- [x]. - Spacing: Use two blank lines between detailed task blocks. Horizontal rules (
---) are reserved for separating major top-level sections.
- Tasks Summary Table:
- Non-Done/open tasks (
triage,pending,in_progress,blocked) are positioned at the top. - Done/done tasks are positioned at the bottom, sorted in ascending numeric order by task ID (
NUT-001,NUT-002,NUT-003, ...).
- Non-Done/open tasks (
- Detailed Tasks Section:
- All detailed task sections remain in strictly ascending numeric order (
NUT-001,NUT-002,NUT-003, ...).
- All detailed task sections remain in strictly ascending numeric order (
- One Task at a Time: Only one task is moved to
in_progressand worked on per development turn. - Verification First: All unit and workspace tests (
cargo test --workspace) and frontend builds (cd gui && npm run build) must pass cleanly before marking a task Done. - Commit Handoff: The agent updates Tasks.md upon task completion and pauses for the user to make the git commit. The agent does not execute commits or destructive git operations.
| Value | Label | Description |
|---|---|---|
triage |
Triage | The task is being evaluated and prioritized. It may still be missing important information. |
pending |
Pending | The task is ready to be acted on. |
in_progress |
In Progress | The task is currently being worked on. |
done |
Done | The task has been completed. |
blocked |
Blocked | The task cannot proceed due to an obstacle or dependency. |
cancelled |
Cancelled | The task was decided against or is no longer relevant. |
| Value | Prefix | Label | Description |
|---|---|---|---|
foundation |
FND | Foundation | Core project setup, repo structure, build system, and shared libraries. |
feature |
FEA | Feature | A new feature to implement. |
bug |
BUG | Bug | A defect or incorrect behavior to fix. |
chore |
CHR | Chore | Routine maintenance or cleanup work. |
integration |
INT | Integration | Connecting components together or integrating external systems. |