# Nextcloud Share for Game Consoles

[![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)

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. Build the 3DS Development Container

Build the container image (first time only, or when Dockerfile changes):

```bash
./scripts/build-container.sh 3ds
```

This creates a complete 3DS development environment with:
- devkitARM GCC 15.2.0
- All 47 available 3DS portlibs
- CIA creation tools (bannertool, makerom, ctrtool)
- Build time: ~10-15 minutes on first build

**Note**: The container is built once and reused. You only rebuild when the Dockerfile changes.

### 3. Compile Your 3DS Project

```bash
# From within your project directory
cd your-3ds-project
podman run --rm -v .:/project:z tomusan/devkitarm-3ds:latest make

# Or specify a path
podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make
```

**Output files**: `.3dsx` (homebrew), `.elf` (debug), `.smdh` (metadata), `.cia` (installable)

### 4. Interactive Development Shell

For debugging or manual builds:

```bash
# Current directory
./scripts/container-shell.sh

# Specific project
./scripts/container-shell.sh ~/my-3ds-game

# With extra volumes or environment
./scripts/container-shell.sh ~/my-game -v /data:/data:z -e DEBUG=1
```

Inside the container, all devkitARM tools are available in PATH. Run `make` to build, `exit` to leave.

### 5. Configure Test Environment (Optional)

For testing with real Nextcloud servers, copy the example configuration:

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

## 🔧 Building

### Using Development Containers

All builds run in isolated containers with complete toolchains. See [docker/README.md](docker/README.md) for detailed container documentation.

**Available containers:**
- **3DS**: `tomusan/devkitarm-3ds:latest` - Nintendo 3DS with full CIA support

**Quick build commands:**
```bash
# Build 3DS container (first time)
./scripts/build-container.sh 3ds

# Compile a 3DS project
podman run --rm -v ~/my-game:/project:z tomusan/devkitarm-3ds:latest make

# Interactive shell
./scripts/container-shell.sh ~/my-game
```

**Build performance:**
- First build: ~10-15 minutes (downloads and compiles tools)
- Subsequent builds: Instant (uses build cache)
- Container rebuilds: Only needed when Dockerfile changes

Platform-specific build instructions:
- [docker/README.md](docker/README.md) - Container usage and CIA creation
- More platforms 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

---

**Note**: This project is in active development. Features and documentation are being added continuously.