diff --git a/.gitignore b/.gitignore index e69de29..9ac71d4 100644 --- a/.gitignore +++ b/.gitignore @@ -0,0 +1,70 @@ +# Local configuration files (contain secrets - do NOT commit) +# Developers should copy config.example to config and add their test credentials +config +*.config +!config.example +!*.config.example + +# Build artifacts +build/ +*.o +*.a +*.so +*.so.* +*.elf +*.3dsx +*.smdh +*.cia +*.3ds +*.rpx +*.wuhb +*.vpk +*.nro +*.nsp + +# CMake +CMakeFiles/ +CMakeCache.txt +cmake_install.cmake +*.cmake +!CMakeLists.txt + +# IDE and editor files +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store +*.code-workspace + +# Container volumes and build contexts +.docker-volumes/ +docker-context/ + +# Test outputs and coverage +test-results/ +coverage/ +*.gcda +*.gcno +*.gcov + +# Platform-specific build directories +3ds/build/ +wiiu/build/ +switch/build/ +vita/build/ +android/build/ +ios/build/ + +# Dependencies +deps/ +third-party/build/ + +# Logs +*.log + +# Temporary files +*.tmp +*.bak +*.cache diff --git a/.plans/CreateProject.md b/.plans/CreateProject.md new file mode 100644 index 0000000..7f89815 --- /dev/null +++ b/.plans/CreateProject.md @@ -0,0 +1,405 @@ +# Project Creation Plan: Nextcloud Share for Game Consoles + +**Created**: 2026-01-26 +**Status**: In Progress +**Target Platform (Initial)**: Nintendo 3DS + +--- + +## Project Overview + +Create a cross-platform homebrew application for game consoles that allows users to upload screenshots, recordings, and other files from their devices to Nextcloud servers. The initial target platform is Nintendo 3DS, with planned support for WiiU, Switch, PS Vita, and potentially Android/iOS/PC. + +### Core Requirements +- C/C++ codebase with shared library for common functionality +- Support for multiple Nextcloud instances via user-provided URLs +- Local filesystem browsing and file selection +- Favorite and recent folder management +- Docker/Podman-based build system (no local toolchain installation required) +- Git-flow workflow with feature branches +- Gitea issue tracking integration + +--- + +## Project Structure + +``` +nextcloud-share/ +├── .plans/ # Feature plans and documentation +├── .github/ # CI/CD workflows (if using GitHub mirror) +├── .gitea/ # Gitea-specific CI workflows +├── shared/ # Shared C/C++ library (libnextcloud) +│ ├── include/ # Public headers +│ ├── src/ # Implementation +│ ├── tests/ # Unit tests +│ └── CMakeLists.txt # Build configuration +├── 3ds/ # Nintendo 3DS homebrew app +│ ├── src/ # 3DS-specific code +│ ├── resources/ # Icons, banners, etc. +│ ├── Makefile # devkitARM build +│ └── README.md # 3DS build instructions +├── docker/ # Dockerfile definitions +│ ├── devkitarm.Dockerfile # 3DS build environment +│ └── README.md # Container usage guide +├── scripts/ # Build and utility scripts +├── config.example # Example configuration file +├── .gitignore +├── README.md +└── LICENSE +``` + +--- + +## Phase 1: Project Initialization + +### 1.1 Repository Setup +- [x] Clone template repository +- [ ] Create repository on git.tomusan.com +- [ ] Configure git-flow (main/develop branches) +- [ ] Add initial .gitignore entries +- [ ] Update README.md with project information + +### 1.2 Configuration Management +- [ ] Create `config.example.json` file with template for: + - Nextcloud URL(s) + - Test username(s) + - Test password(s) + - Build-time options (maxRecentFolders, etc.) +- [ ] Document environment variable overrides for CI: + - `NEXTCLOUD_TEST_URL` + - `NEXTCLOUD_TEST_USER` + - `NEXTCLOUD_TEST_PASSWORD` + - Environment variables take precedence over JSON config +- [ ] Add `config.json` and `config` to .gitignore +- [ ] Add documentation about local config setup +- [ ] Integrate nlohmann/json (header-only, no build dependency) + +### 1.3 Docker/Podman Build Environment +- [ ] Create Dockerfile for devkitARM (3DS development) +- [ ] Create build scripts for containerized compilation +- [ ] Document podman commands for: + - Building container images + - Running builds + - Running tests + - Interactive development shell +- [ ] Test container build process + +--- + +## Phase 2: Shared Library (libnextcloud) + +### 2.1 Library Architecture +- [ ] Define public API interface (C++17) +- [ ] Set up CMake build system for shared library +- [ ] Integrate nlohmann/json (header-only) +- [ ] Integrate Google Test for unit testing +- [ ] Implement WebDAV client for Nextcloud + - HTTP/HTTPS client wrapper (libcurl) + - WebDAV protocol implementation (PROPFIND, PUT, MKCOL) + - XML response parsing (tinyxml2) +- [ ] Authentication handling (HTTP Basic Auth initially) +- [ ] File upload functionality with chunking support +- [ ] Folder listing/browsing via WebDAV PROPFIND +- [ ] Configuration management (JSON parsing and validation) + +### 2.2 Core Features +- [ ] Connection manager + - URL validation + - Server connectivity testing + - Authentication verification +- [ ] Upload manager + - File streaming + - Progress tracking + - Error handling and retry logic +- [ ] Folder management + - List remote folders + - Create folders + - Save favorite folders + - Track recent folders (configurable limit) + +### 2.3 Testing +- [ ] Unit tests for WebDAV client +- [ ] Integration tests with test Nextcloud instances +- [ ] Mock server for offline testing + +--- + +## Phase 3: Nintendo 3DS Implementation + +### 3.1 3DS-Specific Development +- [ ] Set up devkitARM build configuration +- [ ] Implement 3DS UI using citro3d/citro2d +- [ ] SD card filesystem access +- [ ] Screenshot/recording detection +- [ ] Integration with shared library +- [ ] CIA and 3DSX packaging + +### 3.2 Features +- [ ] Main menu UI +- [ ] Nextcloud server configuration screen +- [ ] File browser (SD card) +- [ ] Upload progress display +- [ ] Settings/preferences screen +- [ ] Favorite folders management +- [ ] Recent folders display + +--- + +## Phase 4: CI/CD and Automation + +### 4.1 Gitea Integration +- [ ] Configure Gitea Actions or webhooks +- [ ] Automated builds on push/PR +- [ ] Run tests in containers +- [ ] Generate build artifacts +- [ ] Update build status badges + +### 4.2 Quality Checks +- [ ] Linting (clang-tidy or similar) +- [ ] Code formatting checks (clang-format) +- [ ] Static analysis +- [ ] Test coverage reporting + +--- + +## Phase 5: Documentation + +### 5.1 User Documentation +- [ ] Installation guide (per platform) +- [ ] Configuration guide +- [ ] Usage instructions +- [ ] FAQ +- [ ] Troubleshooting guide + +### 5.2 Developer Documentation +- [ ] Architecture overview +- [ ] API documentation (Doxygen?) +- [ ] Build instructions (local and container) +- [ ] Contributing guidelines +- [ ] Code style guide + +--- + +## Dependencies + +### Build Dependencies (in containers) +- **Nintendo 3DS**: + - devkitARM + - libctru + - citro3d / citro2d (for UI) + - makerom (for CIA generation) + - tex3ds (for texture conversion) + +### Library Dependencieswith SSL/TLS support (mbedTLS for embedded platforms) +- **XML Parsing**: tinyxml2 (lightweight, for WebDAV PROPFIND responses) +- **JSON**: nlohmann/json v3.11+ (header-only, for config files) +- **Testing**: Google Test (gtest) v1.14+ +- **Build System**: CMake 3.15+ + +### C++ Requirements +- **Standard**: C++17 +- **Compiler Support**: + - GCC 7+ (devkitARM) + - Clang 5+ + - MSVC 2017+ (for Windows builds) + - Android NDK r19+g files) +- **Testing**: Catch2 or Google Test (optional) + +### Runtime Dependencies +- User's Nextcloud server (version 20+ recommended) +- Network connectivity on device +- SD card (for 3DS) with sufficient space + +--- + +## Gitea Issues to Create + +The following issues should be created on git.tomusan.com for tracking: + +### Epic/Milestone Issues +1. **#1: Project Infrastructure Setup** + - Description: Set up repository, CI/CD, Docker containers, and documentation + - Labels: infrastructure, epic + +2. **#2: Shared Library Development (libnextcloud)** + - Description: Develop shared C/C++ library for Nextcloud connectivity + - Labels: library, core, epic + +3. **#3: Nintendo 3DS Homebrew App** + - Description: Develop 3DS-specific homebrew application + - Labels: platform:3ds, epic + +### Infrastructure Issues (Milestone #1) +4. **#4: Configure git-flow workflow** + - Description: Initialize git-flow with main/develop branches + - Labels: infrastructure, setup + +5. **#5: Create Docker build environment for devkitARM** + - Description: Dockerfile and scripts for 3DS compilation + - Labels: infrastructure, docker, 3ds + +6. **#6: Set up configuration file system** + - Description: Create config.example and document environment variable overrides + - Labels: infrastructure, configuration + +7. **#7: Implement Gitea CI/CD pipeline** + - Description: Automated builds, tests, and status badges + - Labels: infrastructure, ci-cd, gitea + +### Shared Library Issues (Milestone #2) +8. **#8: Design and implement WebDAV client** + - Description: HTTP client for Nextcloud's WebDAV API + - Labels: library, core, networking + +9. **#9: Implement authentication system** + - Description: Handle Basic Auth and session management + - Labels: library, core, security + +10. **#10: Implement file upload functionality** + - Description: Streaming uploads with progress tracking + - Labels: library, core, feature + +11. **#11: Implement folder management** + - Description: List, create, and navigate remote folders + - Labels: library, core, feature + +12. **#12: Implement favorites and recent folders** + - Description: Persistence layer for user preferences + - Labels: library, feature + +13. **#13: Write unit tests for shared library** + - Description: Test coverage for core functionality + - Labels: library, testing + +### 3DS Platform Issues (Milestone #3) +14. **#14: Initialize 3DS project structure** + - Description: Set up devkitARM build files and basic app skeleton + - Labels: platform:3ds, setup + +15. **#15: Implement 3DS UI framework** + - Description: Menu system and screens using citro2d + - Labels: platform:3ds, ui + +16. **#16: Implement SD card file browser** + - Description: Browse and select files from SD card + - Labels: platform:3ds, feature + +17. **#17: Integrate shared library with 3DS app** + - Description: Link libnextcloud and implement network stack + - Labels: platform:3ds, integration + +18. **#18: Implement 3DS settings screen** + - Description: Server configuration and preferences UI + - Labels: platform:3ds, ui, feature + +19. **#19: Create CIA and 3DSX distribution packages** + - Description: Packaging scripts and testing + - Labels: platform:3ds, distribution + +### Documentation Issues +20. **#20: Write user documentation** + - Description: Installation, configuration, and usage guides + - Labels: documentation, user-facing + +21. **#21: Write developer documentation** + - Description: Architecture, API docs, contributing guide + - Labels: documentation, developer + +--- + +## .gitignore Updates + +Add the following entries: +```gitignore +# Local configuration (contains secrets) +config +*.config +!config.example +!*.config.example + +# Build artifacts +build/ +*.o +*.a +*.so +*.elf +*.3dsx +*.smdh +*.cia +*.3ds + +# IDE and editor files +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# Container volumes +.docker-volumes/ + +# Test outputs +test-results/ +coverage/ + +# Platform-specific +3ds/build/ +wiiu/build/ +switch/build/ +vita/build/ +``` + +--- + +## README.md Updates + +Key sections to add: +1. Project description and goals +2. Supported platforms (current and planned) +3. Features list +4. Prerequisites (Podman/Docker) +5. Quick start guide +6. Building instructions (using containers) +7. Configuration setup +8. Contributing guidelines +9. License information +10. Build status badges (once CI is set up) + +--- + +## Next Steps + +1. **Discuss and refine issue content** - Review each planned issue and adjust descriptions, acceptance criteria, and priorities +2. **Create plan for issue creation** - `.plans/CreateGiteaIssues.md` +3. **Create issues on Gitea** - Bulk create or create incrementally +4. **Set up git-flow** - Initialize develop branch +5. **Implement issues sequentially** - Starting with infrastructure (#4-#7) + +--- + +## Technical Decisions + +### Resolved +- [x] **C++ Standard**: C++17 (best balance of modern features and cross-platform support) +- [x] **Build System**: CMake (industry standard, excellent cross-platform support) +- [x] **Testing Framework**: Google Test (gtest/gmock) +- [x] **Project License**: MIT License +- [x] **Config Format**: JSON using nlohmann/json (header-only library) +- [x] **Nextcloud API**: WebDAV (same protocol as desktop sync client) + +### To Be Resolved +- [ ] Should we support OAuth2 flow or just Basic Auth initially? (Start with Basic Auth) +- [ ] Preferred UI library for 3DS (citro2d, custom, or existing framework)? +- [ ] SSL/TLS library: mbedTLS, OpenSSL, or platform-specific? +- [ ] HTTP library: libcurl (if available) or custom implementation? + +--- + +## Notes + +- Test URLs: `https://cloud.tomusan.com` and `https://disobedient.cloud/nextcloud` +- These should only be in local config files, never committed +- CI should support environment variable injection for test credentials +- Build container should be versioned and tagged for reproducibility +- Consider multi-stage Docker builds to minimize image size diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1e41dec --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Tom Hicks and Nextcloud Share Contributors + +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. diff --git a/README.md b/README.md index e6a825a..0af226f 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,212 @@ -# Project Template +# Nextcloud Share for Game Consoles -This repository is a starter template. -Replace this README with documentation specific to your project once you begin development. +[![Build Status](https://git.tomusan.com/badges/build-status.svg)](https://git.tomusan.com) +[![License](https://img.shields.io/badge/license-TBD-blue.svg)](LICENSE) -The notes below apply only if you choose to build a Node.js project using this template. +A cross-platform homebrew application for game consoles that enables users to upload screenshots, recordings, and other files directly from their devices to Nextcloud servers. + +## 🎮 Supported Platforms + +### Current +- **Nintendo 3DS** (CIA and 3DSX formats) + +### Planned +- Nintendo Switch +- Nintendo Wii U +- PlayStation Vita +- Android / iOS +- PC (Windows, Linux, macOS) + +## ✨ Features + +- 📁 Browse local filesystem (SD card, internal storage) +- ☁️ Upload files directly to Nextcloud via WebDAV +- 🔗 Support for custom Nextcloud server URLs +- ⭐ Save favorite upload folders +- 🕐 Quick access to recently used folders +- 🔒 Secure credential storage +- 📊 Upload progress tracking +- 🎯 User-friendly interface optimized for each platform + +## 🏗️ Project Structure + +``` +nextcloud-share/ +├── shared/ # Shared C/C++ library (libnextcloud) +├── 3ds/ # Nintendo 3DS homebrew app +├── docker/ # Container definitions for build environments +├── scripts/ # Build and utility scripts +└── .plans/ # Feature plans and documentation +``` + +## 📋 Prerequisites + +To build this project, you only need: + +- **Podman** (or Docker) - All build tools run in containers +- **Git** - For version control + +You do **NOT** need to install: +- devkitARM, devkitPro, or other platform SDKs +- Platform-specific toolchains +- Cross-compilers + +Everything runs in isolated containers! + +## 🚀 Quick Start + +### 1. Clone the Repository + +```bash +git clone https://git.tomusan.com/your-username/nextcloud-share.git +cd nextcloud-share +``` + +### 2. Configure Test Environment + +Copy the example configuration file: + +```bash +cp config.example config +``` + +Edit `config` and add your test Nextcloud credentials: + +```ini +# Local test configuration - DO NOT COMMIT THIS FILE +NEXTCLOUD_URL=https://your-nextcloud-instance.com +NEXTCLOUD_USER=your-username +NEXTCLOUD_PASSWORD=your-password +``` + +**Note**: The `config` file is in `.gitignore` and will never be committed. Each developer should create their own local config. + +### 3. Build Using Podman + +#### Build the 3DS version: + +```bash +# Build the container image (first time only) +podman build -f docker/devkitarm.Dockerfile -t nextcloud-share-3ds . + +# Compile the project +podman run --rm -v ./:/project:z nextcloud-share-3ds make -C 3ds + +# Output files will be in 3ds/build/ +``` + +#### Run tests: + +```bash +podman run --rm -v ./:/project:z nextcloud-share-3ds make test +``` + +#### Interactive development shell: + +```bash +podman run --rm -it -v ./:/project:z nextcloud-share-3ds bash +``` + +## 🔧 Building + +Detailed build instructions for each platform will be added as they are implemented. See platform-specific README files: + +- [3ds/README.md](3ds/README.md) - Nintendo 3DS build instructions +- More coming soon... + +## ⚙️ Configuration + +### Local Development Configuration + +The `config` file (copied from `config.example`) is used for local testing: + +```ini +NEXTCLOUD_URL=https://cloud.example.com +NEXTCLOUD_USER=testuser +NEXTCLOUD_PASSWORD=testpass +MAX_RECENT_FOLDERS=5 # Build-time option +``` + +### CI/CD Environment Variables + +For CI/CD pipelines, use environment variables to override the local config: + +- `NEXTCLOUD_TEST_URL` - Test server URL +- `NEXTCLOUD_TEST_USER` - Test username +- `NEXTCLOUD_TEST_PASSWORD` - Test password +- `MAX_RECENT_FOLDERS` - Number of recent folders to track + +Example: + +```bash +NEXTCLOUD_TEST_URL=https://cloud.tomusan.com \ +NEXTCLOUD_TEST_USER=ci-user \ +NEXTCLOUD_TEST_PASSWORD=ci-pass \ +podman run --rm -v ./:/project:z nextcloud-share-3ds make +``` + +## 🧪 Testing + +```bash +# Run unit tests +podman run --rm -v ./:/project:z nextcloud-share-3ds make test + +# Run integration tests (requires valid Nextcloud credentials in config) +podman run --rm -v ./:/project:z nextcloud-share-3ds make integration-test +``` + +## 🤝 Contributing + +We use the **git-flow** workflow: + +1. Fork the repository +2. Create a feature branch: `git checkout -b feature/my-feature develop` +3. Commit your changes following our style guide +4. Push to your fork and submit a pull request to `develop` + +See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines (coming soon). + +## 📝 Development Workflow + +1. Issues are tracked on Gitea: https://git.tomusan.com +2. Feature plans are documented in `.plans/` +3. Each feature gets its own branch following git-flow conventions +4. All builds and tests run in containers +5. CI/CD automatically validates pull requests + +## 🗺️ Roadmap + +See [.plans/CreateProject.md](.plans/CreateProject.md) for the complete project plan and milestones. + +Key upcoming features: +- ✅ Nintendo 3DS support +- ⏳ Additional platform support (Switch, Wii U, Vita) +- ⏳ OAuth2 authentication +- ⏳ Automatic screenshot detection +- ⏳ Folder synchronization + +## 📖 Documentation + +- [Project Creation Plan](.plans/CreateProject.md) +- [User Guide](docs/user-guide.md) *(coming soon)* +- [Developer Guide](docs/developer-guide.md) *(coming soon)* +- [API Documentation](docs/api.md) *(coming soon)* + +## 📄 License + +[License TBD - to be determined] + +## 🙏 Acknowledgments + +- devkitPro team for homebrew toolchains +- Nextcloud community +- All contributors to this project + +## 📞 Support + +- Issue Tracker: https://git.tomusan.com/your-username/nextcloud-share/issues +- Documentation: https://git.tomusan.com/your-username/nextcloud-share/wiki --- -## If your project will use Node.js - -Use Node 22 or newer for development. - -Check your version: - -``` -node --version -``` - -If your version is older than 22, update using nvm: - -``` -nvm install --lts -``` - -(Optional) Make the new version your default: - -``` -nvm alias default -``` - -After running `yarn init`, you may add a minimum Node version requirement to your `package.json`: - -```json -"engines": { - "node": ">=22" -} -``` - -This helps ensure you do not accidentally use an outdated Node version. - ---- - -## If your project will use Yarn (Berry) - -This template assumes modern Yarn (Yarn 4+), managed by Corepack. - -Enable Corepack: - -``` -corepack enable -``` - -Update Yarn to the latest stable version: - -``` -corepack prepare yarn@stable --activate -``` - -Install dependencies: - -``` -yarn install -``` - -If you want Yarn to error (instead of warn) when the Node version does not satisfy the `engines` field, add this to `.yarnrc.yml`: - -```yaml -enableStrictEngineChecks: true -``` - ---- - -## If your project will use containers - -If you plan to build or deploy using Docker, choose a base image that matches your development environment. -For Node.js projects, a common choice is: - -``` -FROM node:24 -``` - ---- - -## Replace this README - -Once you know what your project will be (Node, C++, Python, etc.), replace this file with documentation specific to your build, run, and deployment steps. +**Note**: This project is in active development. Features and documentation are being added continuously.