maj/NextcloudUploadTool
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
8a7a201daaba3ab35e4bec322d8b6016e0a86e08
NextcloudUploadTool/Tasks.md

24 KiB
Raw Blame History

project, task-statuses, task-types
project task-statuses task-types
name id prefix
Nextcloud Upload Tool nextcloud-upload-tool NUT
value label description
triage Triage The task is being evaluated and prioritized. It may still be missing important information.
value label description
pending Pending The task is ready to be acted on.
value label description
in_progress In Progress The task is currently being worked on.
value label description
done Fixed The task has been completed.
value label description
blocked Blocked The task cannot proceed due to an obstacle or dependency.
value label description
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.
value prefix label description
feature FEA Feature A new feature to implement.
value prefix label description
bug BUG Bug A defect or incorrect behavior to fix.
value prefix label description
chore CHR Chore Routine maintenance or cleanup work.
value prefix label description
integration INT Integration Connecting components together or integrating external systems.

Nextcloud Upload Tool — Project Plan

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.

Task Management Quick Guide

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.

Tasks Summary (Rendered from task-details)

ID Title Status Type
NUT-019 Implement Homebrew/Winget/Chocolatey Manifests Triage Chore
NUT-023 Write Comprehensive CLI Documentation and Automation Guides Triage Chore
NUT-024 Create Docker/Podman Nextcloud Integration Test Harness Triage Foundation
NUT-001 Establish Repository Structure Fixed Foundation
NUT-002 Implement Shared Rust Backend Library Fixed Foundation
NUT-003 Implement WebDAV Upload Logic Fixed Feature
NUT-004 Implement OCS Share Link Generation Fixed Feature
NUT-005 Implement Direct Download URL Builder Fixed Feature
NUT-006 Implement Credential Storage System Fixed Feature
NUT-007 Implement Multi-Account Support (Backend) Fixed Feature
NUT-008 Implement CLI Frontend Fixed Feature
NUT-009 Implement CLI Output Formatting Options Fixed Feature
NUT-010 Implement CLI Multi-file Upload Support Fixed Feature
NUT-011 Implement CLI Progress Reporting + pv Support Fixed Feature
NUT-012 Implement GUI (Tauri) Frontend Fixed Feature
NUT-013 Implement GUI File Queue + Drag-and-Drop Fixed Feature
NUT-014 Implement GUI Credential Management UI Fixed Feature
NUT-015 Implement GUI Upload Progress Bars Fixed Feature
NUT-016 Implement Shared Auth Token Reuse Fixed Integration
NUT-017 Implement Multi-Account Switching (GUI + CLI) Fixed Integration
NUT-018 Implement Packaging for macOS, Windows, Linux Fixed Chore
NUT-020 Write Documentation + Examples Fixed Chore
NUT-021 Support Headless & SSH Remote Authentication Modes Fixed Feature
NUT-022 Implement CLI Shell Completions Generation Fixed Feature

Detailed Tasks

Establish Repository Structure

ID: NUT-001
Status: Fixed
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 .editorconfig and .gitignore
  • Add README with project overview

Dependencies:
None

Implement Shared Rust Backend Library

ID: NUT-002
Status: Fixed
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 NextcloudClient struct
  • Implement async runtime setup
  • Define error types
  • Define configuration structs
  • Provide high-level API for upload + share

Dependencies:

  • NUT-001

Implement WebDAV Upload Logic

ID: NUT-003
Status: Fixed
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

Implement OCS Share Link Generation

ID: NUT-004
Status: Fixed
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

Implement Direct Download URL Builder

ID: NUT-005
Status: Fixed
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

Implement Credential Storage System

ID: NUT-006
Status: Fixed
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

Implement Multi-Account Support (Backend)

ID: NUT-007
Status: Fixed
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

Implement CLI Frontend

ID: NUT-008
Status: Fixed
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 login command (browser-based Login Flow v2)
  • Add upload command
  • Add --account flag
  • Add --stdin support
  • Add error reporting

Dependencies:

  • NUT-003
  • NUT-004
  • NUT-005
  • NUT-006

Implement CLI Output Formatting Options

ID: NUT-009
Status: Fixed
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

Implement CLI Multi-file Upload Support

ID: NUT-010
Status: Fixed
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

Implement CLI Progress Reporting + pv Support

ID: NUT-011
Status: Fixed
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 --size hint 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-progress flag
  • Support piping directly from pv or Unix pipelines without display conflicts

Dependencies:

  • NUT-003
  • NUT-008

Implement GUI (Tauri) Frontend

ID: NUT-012
Status: Fixed
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

Implement GUI File Queue + Drag-and-Drop

ID: NUT-013
Status: Fixed
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

Implement GUI Credential Management UI

ID: NUT-014
Status: Fixed
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

Implement GUI Upload Progress Bars

ID: NUT-015
Status: Fixed
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

Implement Shared Auth Token Reuse

ID: NUT-016
Status: Fixed
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

Implement Multi-Account Switching (GUI + CLI)

ID: NUT-017
Status: Fixed
Type: Integration

Description:
Add multi-account switching to both CLI and GUI.

Requirements:

  • CLI --account flag
  • GUI dropdown
  • Shared backend logic

Dependencies:

  • NUT-007
  • NUT-008
  • NUT-014

Implement Packaging for macOS, Windows, Linux

ID: NUT-018
Status: Fixed
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

Implement Homebrew/Winget/Chocolatey Manifests

ID: NUT-019
Status: Triage
Type: Chore

Description:
Add package manager manifests for easy installation.

Requirements:

  • Homebrew formula
  • Winget manifest
  • Chocolatey package
  • AUR PKGBUILD

Dependencies:

  • NUT-018

Write Documentation + Examples

ID: NUT-020
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

Dependencies:

  • NUT-012
  • NUT-017
  • NUT-018

Support Headless & SSH Remote Authentication Modes

ID: NUT-021
Status: Fixed
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-browser flag 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

Implement CLI Shell Completions Generation

ID: NUT-022
Status: Fixed
Type: Feature

Description:
Add automated shell completion script generation using clap_complete for major shells (bash, zsh, fish, powershell, elvish).

Requirements:

  • Add clap_complete crate dependency
  • Implement nut completions <SHELL> subcommand
  • Support bash, zsh, fish, powershell, and elvish output to stdout
  • Include quick installation instructions in command help

Dependencies:

  • NUT-008

Write Comprehensive CLI Documentation and Automation Guides

ID: NUT-023
Status: Triage
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 in README.md
  • Provide practical recipes for piping data (stdin, pv, curl, mysqldump)
  • Provide scripting examples parsing --json, --tsv, --url-only, and --direct-url-only with jq and xargs
  • Document headless SSH and CI/CD automated provisioning with --username and --app-password

Dependencies:

  • NUT-008
  • NUT-009
  • NUT-010
  • NUT-011
  • NUT-021

Create Docker/Podman Nextcloud Integration Test Harness

ID: NUT-024
Status: Triage
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.rs or cli/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

Task System Documentation & Rules

This section defines how contributors and AI agents must interpret, update, and maintain this Tasks.md file.

Single Source of Truth (SSOT)

  • Task Anchor Tag: The HTML anchor tag directly above each task title is the SSOT for machine-readable attributes:
    • Task ID: id attribute (lowercase, e.g. id="nut-001")
    • Task Status: data-status attribute (must match a value in task-statuses frontmatter)
    • Task Type: data-task-type attribute (must match a value in task-types frontmatter)
  • 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.
  • Rendered Sections: Tables marked as (Rendered from ...) are non-canonical views generated from frontmatter and task anchor/detail sections.

Task Lifecycle & Status Values

Tasks progress through defined statuses:

  1. triage: Under initial evaluation and specification. Missing requirements allowed.
  2. pending: Scope defined and ready for active work.
  3. in_progress: Active implementation in progress.
  4. done: Fixed. Work complete, requirements checked, and verified.
  5. blocked: Blocked by an external obstacle or unmet dependency.
  6. cancelled: Deprecated or abandoned.

Formatting & Identification Invariants

  • Task ID Schema: ${project.prefix}-XXX where XXX is 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.

Table & Section Sorting Rules

  • Tasks Summary Table:
    • Non-fixed/open tasks (triage, pending, in_progress, blocked) are positioned at the top.
    • Fixed/done tasks are positioned at the bottom, sorted in ascending numeric order by task ID (NUT-001, NUT-002, NUT-003, ...).
  • Detailed Tasks Section:
    • All detailed task sections remain in strictly ascending numeric order (NUT-001, NUT-002, NUT-003, ...).

Contributor & Agent Workflow

  1. One Task at a Time: Only one task is moved to in_progress and worked on per development turn.
  2. 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 Fixed.
  3. 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.

Task Statuses (Rendered from task-statuses)

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 Fixed 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.

Task Types (Rendered from task-types)

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.
Reference in New Issue View Git Blame Copy Permalink