nextcloud-share/README.md

# 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.json config.json
```

Edit `config.json` and add your test Nextcloud credentials:

```json
{
  "nextcloud": {
    "url": "https://your-nextcloud-instance.com",
    "username": "your-username",
    "password": "your-app-password"
  },
  "settings": {
    "maxRecentFolders": 5,
    "uploadChunkSize": 10485760
  }
}
```

**Note**: The `config.json` 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 project uses a JSON configuration file for managing test credentials and build options.

**Setup:**
```bash
# Copy the example configuration
cp config.example.json config.json

# Edit config.json with your credentials
nano config.json
```

**Configuration structure:**
```json
{
  "nextcloud": {
    "url": "https://cloud.example.com",
    "username": "testuser",
    "password": "your-app-password"
  },
  "settings": {
    "maxRecentFolders": 5,
    "uploadChunkSize": 10485760
  }
}
```

**Loading configuration:**
```bash
# Load configuration and export as environment variables
source scripts/load-config.sh

# Validate configuration
./scripts/validate-config.sh
```

### Environment Variable Overrides

Environment variables take precedence over JSON configuration values. This is useful for CI/CD pipelines where you don't want to store credentials in files.

**Supported environment variables:**
- `NEXTCLOUD_URL` - Nextcloud server URL (required)
- `NEXTCLOUD_USER` - Username for authentication (required)
- `NEXTCLOUD_PASSWORD` - Password or app password (required)
- `MAX_RECENT_FOLDERS` - Number of recent folders to track (default: 5)
- `UPLOAD_CHUNK_SIZE` - Upload chunk size in bytes (default: 10485760)
- `CONFIG_FILE` - Path to config file (default: config.json)

**CI/CD Example:**
```bash
# Override configuration with environment variables
export NEXTCLOUD_URL=https://cloud.tomusan.com
export NEXTCLOUD_USER=ci-user
export NEXTCLOUD_PASSWORD=ci-pass

# Load any remaining config from file
source scripts/load-config.sh

# Run tests
podman run --rm \
  -e NEXTCLOUD_URL \
  -e NEXTCLOUD_USER \
  -e NEXTCLOUD_PASSWORD \
  -v ./:/project:z \
  tomusan/devkitarm-3ds:latest \
  make test
```

## 🧪 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.