feat(config): implement configuration system and contributing guide (#6, #4)

.gitignore

@@ -1,10 +1,12 @@
 # Local configuration files (contain secrets - do NOT commit)
 # Developers should copy config.example to config and add their test credentials
-config
+config.json
-*.config
 !config.example
 !*.config.example
 
+# Gitea API documentation (downloaded for reference, not part of source)
+gitea-swagger.v1.json
+
 # Build artifacts
 build/
 *.o

CONTRIBUTING.md

@@ -0,0 +1,410 @@
+# Contributing to Nextcloud Share
+
+Thank you for your interest in contributing to Nextcloud Share! This document provides guidelines and workflows for contributing to the project.
+
+---
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [Git Workflow](#git-workflow)
+- [Development Setup](#development-setup)
+- [Making Changes](#making-changes)
+- [Submitting a Pull Request](#submitting-a-pull-request)
+- [Issue Guidelines](#issue-guidelines)
+- [Commit Message Guidelines](#commit-message-guidelines)
+
+---
+
+## Code of Conduct
+
+We expect all contributors to be respectful, inclusive, and professional. Please:
+
+- Be welcoming to newcomers
+- Provide constructive feedback
+- Focus on what is best for the community
+- Show empathy towards other community members
+
+---
+
+## Getting Started
+
+1. **Fork the repository** on Gitea (if external contributor)
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://git.tomusan.com/maj/nextcloud-share.git
+   cd nextcloud-share
+   ```
+3. **Add upstream remote** (if forked):
+   ```bash
+   git remote add upstream https://git.tomusan.com/maj/nextcloud-share.git
+   ```
+
+---
+
+## Git Workflow
+
+This project uses the **git-flow** branching model. Understanding this workflow is essential for contributing.
+
+### Branch Structure
+
+#### `main` - Production Branch
+- **Purpose**: Contains production-ready, stable releases only
+- **Rules**: 
+  - Never commit directly to `main`
+  - Only receives merges from `release/*` or `hotfix/*` branches
+  - Every commit on `main` is tagged with a version number
+  - Represents the current production state
+
+#### `develop` - Integration Branch
+- **Purpose**: Integration branch where features come together
+- **Rules**:
+  - Default branch for development
+  - Never commit directly to `develop`
+  - Receives merges from `feature/*` branches
+  - Always contains the latest delivered development changes
+  - Should always be in a working state
+
+#### `feature/*` - Feature Branches
+- **Purpose**: Develop new features or enhancements
+- **Naming**: `feature/<issue-number>-<short-description>`
+  - Example: `feature/8-webdav-client`
+- **Branch from**: `develop`
+- **Merge into**: `develop`
+- **Lifetime**: Deleted after merge
+
+**Creating a feature branch**:
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/8-webdav-client
+```
+
+**Merging a feature**:
+```bash
+git checkout develop
+git merge --no-ff feature/8-webdav-client
+git push origin develop
+git branch -d feature/8-webdav-client
+```
+
+#### `release/*` - Release Preparation Branches
+- **Purpose**: Prepare for a new production release
+- **Naming**: `release/v<version>`
+  - Example: `release/v0.1.0`
+- **Branch from**: `develop`
+- **Merge into**: `main` AND `develop`
+- **Lifetime**: Deleted after merge
+
+**Creating a release branch**:
+```bash
+git checkout develop
+git checkout -b release/v0.1.0
+# Bump version numbers, update CHANGELOG, etc.
+```
+
+**Finishing a release**:
+```bash
+# Merge to main
+git checkout main
+git merge --no-ff release/v0.1.0
+git tag -a v0.1.0 -m "Release version 0.1.0"
+git push origin main --tags
+
+# Merge back to develop
+git checkout develop
+git merge --no-ff release/v0.1.0
+git push origin develop
+
+# Delete release branch
+git branch -d release/v0.1.0
+```
+
+#### `hotfix/*` - Emergency Fix Branches
+- **Purpose**: Quick fixes for critical production bugs
+- **Naming**: `hotfix/v<version>-<description>`
+  - Example: `hotfix/v0.1.1-fix-crash`
+- **Branch from**: `main`
+- **Merge into**: `main` AND `develop`
+- **Lifetime**: Deleted after merge
+
+**Creating a hotfix**:
+```bash
+git checkout main
+git checkout -b hotfix/v0.1.1-fix-crash
+# Make the fix
+```
+
+**Finishing a hotfix**:
+```bash
+# Merge to main
+git checkout main
+git merge --no-ff hotfix/v0.1.1-fix-crash
+git tag -a v0.1.1 -m "Hotfix version 0.1.1"
+git push origin main --tags
+
+# Merge to develop
+git checkout develop
+git merge --no-ff hotfix/v0.1.1-fix-crash
+git push origin develop
+
+# Delete hotfix branch
+git branch -d hotfix/v0.1.1-fix-crash
+```
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- **Podman** (preferred) or **Docker**
+- **Git**
+- **jq** (for config parsing)
+
+### Configuration
+
+1. **Copy the example config**:
+   ```bash
+   cp config.example.json config.json
+   ```
+
+2. **Edit `config.json`** with your Nextcloud test credentials:
+   ```json
+   {
+     "nextcloud": {
+       "url": "https://cloud.tomusan.com",
+       "username": "your-username",
+       "password": "your-app-password"
+     }
+   }
+   ```
+
+3. **Never commit `config.json`** - it's in `.gitignore`
+
+### Building with Containers
+
+All builds should be done inside containers to ensure consistency:
+
+```bash
+# Build 3DS app (when available)
+podman build -f docker/devkitarm.Dockerfile -t nextcloud-share-3ds .
+podman run --rm -v ./:/project:z nextcloud-share-3ds make -C 3ds
+
+# Build shared library (when available)
+podman build -f docker/builder.Dockerfile -t builder .
+podman run --rm -v ./:/project:z builder cmake -B build -S shared
+podman run --rm -v ./:/project:z builder cmake --build build
+```
+
+---
+
+## Making Changes
+
+### 1. Find or Create an Issue
+
+- Check [existing issues](https://git.tomusan.com/maj/nextcloud-share/issues)
+- Create a new issue if needed
+- Get issue number (e.g., `#42`)
+
+### 2. Create a Feature Branch
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/42-short-description
+```
+
+### 3. Make Your Changes
+
+- Write clean, maintainable code
+- Follow existing code style
+- Add tests for new functionality
+- Update documentation as needed
+- Test your changes thoroughly
+
+### 4. Commit Your Changes
+
+Follow the [commit message guidelines](#commit-message-guidelines):
+
+```bash
+git add <files>
+git commit -m "feat: add WebDAV client implementation (#42)"
+```
+
+### 5. Keep Your Branch Updated
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout feature/42-short-description
+git rebase develop
+```
+
+### 6. Push Your Branch
+
+```bash
+git push origin feature/42-short-description
+```
+
+---
+
+## Submitting a Pull Request
+
+1. **Push your feature branch** to the repository
+2. **Open a Pull Request** on Gitea:
+   - Base: `develop`
+   - Compare: `feature/42-short-description`
+3. **Fill out the PR template**:
+   - Reference the issue number (e.g., "Closes #42")
+   - Describe what changed and why
+   - Add any testing notes
+4. **Wait for review**:
+   - Address any feedback
+   - Push additional commits if needed
+   - CI must pass before merge
+
+### PR Checklist
+
+- [ ] Branch is up-to-date with `develop`
+- [ ] All tests pass locally
+- [ ] New tests added for new features
+- [ ] Documentation updated
+- [ ] Commit messages follow guidelines
+- [ ] CI pipeline passes
+- [ ] Code has been self-reviewed
+- [ ] No sensitive data (passwords, tokens) in commits
+
+---
+
+## Issue Guidelines
+
+### Creating Issues
+
+- **Use a clear, descriptive title**
+- **Provide context**: What are you trying to do?
+- **Include reproduction steps** for bugs
+- **Add relevant labels**: `bug`, `feature`, `platform:3ds`, etc.
+- **Reference related issues** if applicable
+
+### Working on Issues
+
+- **Comment on the issue** before starting work to avoid duplication
+- **Update the issue** with progress notes
+- **Link commits** to issues using `#<issue-number>` in commit messages
+- **Close issues** with "Closes #<number>" or "Fixes #<number>" in PR description
+
+---
+
+## Commit Message Guidelines
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### Format
+
+```
+<type>(<scope>): <subject> (#<issue>)
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- **feat**: New feature
+- **fix**: Bug fix
+- **docs**: Documentation changes
+- **style**: Code style changes (formatting, no logic change)
+- **refactor**: Code refactoring
+- **test**: Adding or updating tests
+- **chore**: Maintenance tasks
+- **ci**: CI/CD changes
+- **perf**: Performance improvements
+
+### Examples
+
+```bash
+# Simple feature
+git commit -m "feat: add WebDAV client implementation (#8)"
+
+# Bug fix
+git commit -m "fix: resolve memory leak in upload manager (#25)"
+
+# With scope
+git commit -m "feat(3ds): implement SD card file browser (#16)"
+
+# With body
+git commit -m "refactor: simplify authentication logic (#9)
+
+The previous implementation had unnecessary complexity.
+This refactoring makes the code more maintainable and easier to test."
+
+# Breaking change
+git commit -m "feat!: change API authentication method (#9)
+
+BREAKING CHANGE: Authentication now requires app passwords instead of
+regular passwords. Update your config.json accordingly."
+```
+
+### Issue References
+
+- **Always include issue number**: `(#42)` in commit message
+- **Close issues** with keywords in PR description:
+  - `Closes #42`
+  - `Fixes #42`
+  - `Resolves #42`
+
+---
+
+## Code Style
+
+### C++
+- **Standard**: C++17
+- **Formatting**: Follow existing style (consider using clang-format)
+- **Naming**:
+  - Classes: `PascalCase`
+  - Functions/methods: `camelCase`
+  - Variables: `snake_case`
+  - Constants: `UPPER_SNAKE_CASE`
+  - Namespaces: `lowercase`
+
+### Python
+- **Standard**: PEP 8
+- **Formatting**: Use Black or autopep8
+
+### Shell Scripts
+- **Use bash** explicitly: `#!/bin/bash`
+- **Quote variables**: `"${VAR}"`
+- **Check return codes**: `if [ $? -eq 0 ]; then`
+
+---
+
+## Testing
+
+- **Write tests** for all new features
+- **Run tests locally** before pushing:
+  ```bash
+  # When available
+  podman run --rm -v ./:/project:z builder ctest --test-dir build
+  ```
+- **Ensure CI passes** before requesting review
+
+---
+
+## Questions?
+
+- **Open an issue** for questions
+- **Comment on relevant issues** for feature discussions
+- **Check existing documentation** in the `docs/` directory
+
+---
+
+## License
+
+By contributing to Nextcloud Share, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing! 🎉

config.example.json

@@ -0,0 +1,11 @@
+{
+  "nextcloud": {
+    "url": "https://cloud.example.com",
+    "username": "your-username",
+    "password": "your-app-password"
+  },
+  "settings": {
+    "maxRecentFolders": 5,
+    "uploadChunkSize": 10485760
+  }
+}

docs/configuration.md

@@ -0,0 +1,203 @@
+# Configuration Setup Guide
+
+This guide explains how to set up your Nextcloud configuration for development and testing.
+
+## Quick Start
+
+1. **Copy the example configuration**:
+   ```bash
+   cp config.example.json config.json
+   ```
+
+2. **Generate a Nextcloud App Password** (recommended for security):
+   - Go to your Nextcloud instance
+   - Navigate to: **Settings → Security → Devices & sessions**
+   - Scroll to "App passwords" section
+   - Enter a name (e.g., "nextcloud-share-dev")
+   - Click "Create new app password"
+   - Copy the generated token
+
+3. **Edit `config.json`** with your credentials:
+   ```json
+   {
+     "nextcloud": {
+       "url": "https://cloud.tomusan.com",
+       "username": "your-username",
+       "password": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+     },
+     "settings": {
+       "maxRecentFolders": 5,
+       "uploadChunkSize": 10485760
+     }
+   }
+   ```
+
+4. **Validate your configuration**:
+   ```bash
+   ./scripts/validate-config.sh
+   ```
+
+## Generating App Passwords
+
+### For cloud.tomusan.com
+
+1. Log in to https://cloud.tomusan.com
+2. Click your profile icon (top right) → Settings
+3. Go to **Security** in the left sidebar
+4. Scroll down to **Devices & sessions**
+5. Under "App passwords" or "App-specific passwords":
+   - Enter a name: `nextcloud-share-dev`
+   - Click **Create new app password**
+6. Copy the generated password (format: `xxxxx-xxxxx-xxxxx-xxxxx-xxxxx`)
+7. Paste it into `config.json` as the `password` field
+
+### For disobedient.cloud/nextcloud
+
+1. Log in to https://disobedient.cloud/nextcloud
+2. Follow the same steps as above
+3. Generate a separate app password for this instance
+
+## Why App Passwords?
+
+App passwords are more secure than using your main account password because:
+
+- ✅ **Limited scope**: Only grants access to files, not account settings
+- ✅ **Revocable**: Can be revoked without changing your main password
+- ✅ **Traceable**: Shows up as a separate session in your account
+- ✅ **Safer storage**: If leaked, doesn't compromise your main account
+
+## Configuration Options
+
+### Required Fields
+
+- **`nextcloud.url`**: Your Nextcloud server URL (must use HTTPS in production)
+- **`nextcloud.username`**: Your Nextcloud username
+- **`nextcloud.password`**: App password or regular password
+
+### Optional Fields
+
+- **`settings.maxRecentFolders`**: Number of recent folders to remember (default: 5)
+- **`settings.uploadChunkSize`**: Upload chunk size in bytes (default: 10485760 = 10MB)
+
+## Environment Variable Overrides
+
+You can override any configuration value with environment variables (useful for CI/CD):
+
+```bash
+# Override config values
+export NEXTCLOUD_URL="https://cloud.example.com"
+export NEXTCLOUD_USER="testuser"
+export NEXTCLOUD_PASSWORD="app-password-here"
+
+# Run your tests
+./scripts/validate-config.sh
+```
+
+Environment variables always take precedence over `config.json`.
+
+## Loading Configuration
+
+To load configuration in your scripts:
+
+```bash
+#!/bin/bash
+source ./scripts/load-config.sh
+
+# Now you have access to:
+# - $NEXTCLOUD_URL
+# - $NEXTCLOUD_USER
+# - $NEXTCLOUD_PASSWORD
+# - $MAX_RECENT_FOLDERS
+# - $UPLOAD_CHUNK_SIZE
+```
+
+## Validating Configuration
+
+The validation script checks:
+
+- ✅ All required fields are present
+- ✅ URL format is valid
+- ✅ HTTPS is used (warns if HTTP)
+- ✅ Numeric settings are valid numbers
+
+```bash
+./scripts/validate-config.sh
+```
+
+## Security Notes
+
+- ⚠️ **Never commit `config.json`** - it's in `.gitignore`
+- ⚠️ **Use HTTPS**, not HTTP
+- ⚠️ **Use app passwords** when possible
+- ⚠️ **Revoke app passwords** when done with a project
+- ⚠️ Keep your `config.json` file permissions restricted:
+  ```bash
+  chmod 600 config.json
+  ```
+
+## Multiple Test Accounts
+
+If you have multiple Nextcloud instances for testing:
+
+**Option 1: Multiple config files**
+```bash
+cp config.example.json config-tomusan.json
+cp config.example.json config-disobedient.json
+
+# Use with:
+CONFIG_FILE=config-tomusan.json ./scripts/validate-config.sh
+```
+
+**Option 2: Environment variables**
+```bash
+export NEXTCLOUD_URL="https://disobedient.cloud/nextcloud"
+export NEXTCLOUD_USER="your-username"
+export NEXTCLOUD_PASSWORD="xxxxx-xxxxx-xxxxx-xxxxx-xxxxx"
+
+./scripts/validate-config.sh
+```
+
+## Troubleshooting
+
+### "jq is not installed"
+
+Install jq on your system:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install jq
+
+# macOS
+brew install jq
+
+# Arch Linux
+sudo pacman -S jq
+```
+
+### "NEXTCLOUD_URL must start with http:// or https://"
+
+Make sure your URL includes the protocol:
+- ✅ `https://cloud.tomusan.com`
+- ❌ `cloud.tomusan.com`
+
+### "Configuration is not valid"
+
+Run with the validation script to see specific errors:
+```bash
+./scripts/validate-config.sh
+```
+
+## CI/CD Configuration
+
+For Gitea Actions or other CI systems, set secrets in your repository:
+
+1. Go to repository **Settings → Secrets**
+2. Add these secrets:
+   - `NEXTCLOUD_TEST_URL`
+   - `NEXTCLOUD_TEST_USER`
+   - `NEXTCLOUD_TEST_PASSWORD`
+3. The CI will use environment variables instead of `config.json`
+
+---
+
+For more information, see [CONTRIBUTING.md](../CONTRIBUTING.md).

scripts/load-config.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Load configuration from JSON file and export as environment variables
+# Environment variables take precedence over JSON values
+
+set -e
+
+# Default config file location
+CONFIG_FILE="${CONFIG_FILE:-config.json}"
+
+# Color output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Function to safely extract JSON values
+get_json_value() {
+    local file="$1"
+    local key="$2"
+    local default="${3:-}"
+    
+    if [ -f "$file" ]; then
+        value=$(jq -r "$key" "$file" 2>/dev/null || echo "null")
+        if [ "$value" = "null" ] || [ -z "$value" ]; then
+            echo "$default"
+        else
+            echo "$value"
+        fi
+    else
+        echo "$default"
+    fi
+}
+
+# Check if config file exists
+if [ ! -f "$CONFIG_FILE" ]; then
+    echo -e "${YELLOW}Warning: $CONFIG_FILE not found${NC}" >&2
+    echo -e "${YELLOW}Using environment variables only${NC}" >&2
+    echo -e "${YELLOW}Copy config.example.json to config.json and fill in your credentials${NC}" >&2
+    echo "" >&2
+fi
+
+# Check if jq is installed
+if ! command -v jq &> /dev/null; then
+    echo -e "${RED}Error: jq is not installed${NC}" >&2
+    echo -e "${RED}Install it with: sudo apt-get install jq${NC}" >&2
+    exit 1
+fi
+
+# Load configuration values, preferring environment variables
+export NEXTCLOUD_URL="${NEXTCLOUD_URL:-$(get_json_value "$CONFIG_FILE" '.nextcloud.url' '')}"
+export NEXTCLOUD_USER="${NEXTCLOUD_USER:-$(get_json_value "$CONFIG_FILE" '.nextcloud.username' '')}"
+export NEXTCLOUD_PASSWORD="${NEXTCLOUD_PASSWORD:-$(get_json_value "$CONFIG_FILE" '.nextcloud.password' '')}"
+
+# Load settings
+export MAX_RECENT_FOLDERS="${MAX_RECENT_FOLDERS:-$(get_json_value "$CONFIG_FILE" '.settings.maxRecentFolders' '5')}"
+export UPLOAD_CHUNK_SIZE="${UPLOAD_CHUNK_SIZE:-$(get_json_value "$CONFIG_FILE" '.settings.uploadChunkSize' '10485760')}"
+
+# Show what was loaded (without showing password)
+if [ -n "$NEXTCLOUD_URL" ]; then
+    echo -e "${GREEN}✓${NC} NEXTCLOUD_URL: $NEXTCLOUD_URL"
+fi
+if [ -n "$NEXTCLOUD_USER" ]; then
+    echo -e "${GREEN}✓${NC} NEXTCLOUD_USER: $NEXTCLOUD_USER"
+fi
+if [ -n "$NEXTCLOUD_PASSWORD" ]; then
+    echo -e "${GREEN}✓${NC} NEXTCLOUD_PASSWORD: [set]"
+fi
+echo -e "${GREEN}✓${NC} MAX_RECENT_FOLDERS: $MAX_RECENT_FOLDERS"
+echo -e "${GREEN}✓${NC} UPLOAD_CHUNK_SIZE: $UPLOAD_CHUNK_SIZE"

scripts/validate-config.sh

@@ -0,0 +1,73 @@
+#!/bin/bash
+# Validate that all required configuration is present
+
+set -e
+
+# Color output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+# Load configuration first
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/load-config.sh" > /dev/null 2>&1 || true
+
+# Validation flags
+VALID=true
+
+# Validate required fields
+if [ -z "$NEXTCLOUD_URL" ]; then
+    echo -e "${RED}✗ Error: NEXTCLOUD_URL is not set${NC}" >&2
+    VALID=false
+fi
+
+if [ -z "$NEXTCLOUD_USER" ]; then
+    echo -e "${RED}✗ Error: NEXTCLOUD_USER is not set${NC}" >&2
+    VALID=false
+fi
+
+if [ -z "$NEXTCLOUD_PASSWORD" ]; then
+    echo -e "${RED}✗ Error: NEXTCLOUD_PASSWORD is not set${NC}" >&2
+    VALID=false
+fi
+
+# Validate URL format
+if [ -n "$NEXTCLOUD_URL" ]; then
+    if [[ ! "$NEXTCLOUD_URL" =~ ^https?:// ]]; then
+        echo -e "${RED}✗ Error: NEXTCLOUD_URL must start with http:// or https://${NC}" >&2
+        VALID=false
+    fi
+    
+    # Warn if using HTTP instead of HTTPS
+    if [[ "$NEXTCLOUD_URL" =~ ^http:// ]]; then
+        echo -e "${RED}⚠ Warning: Using HTTP instead of HTTPS is insecure!${NC}" >&2
+    fi
+fi
+
+# Validate numeric settings
+if ! [[ "$MAX_RECENT_FOLDERS" =~ ^[0-9]+$ ]]; then
+    echo -e "${RED}✗ Error: MAX_RECENT_FOLDERS must be a number${NC}" >&2
+    VALID=false
+fi
+
+if ! [[ "$UPLOAD_CHUNK_SIZE" =~ ^[0-9]+$ ]]; then
+    echo -e "${RED}✗ Error: UPLOAD_CHUNK_SIZE must be a number${NC}" >&2
+    VALID=false
+fi
+
+# Exit with appropriate code
+if [ "$VALID" = true ]; then
+    echo -e "${GREEN}✓ Configuration is valid${NC}"
+    exit 0
+else
+    echo ""
+    echo "Please set the missing configuration values in:"
+    echo "  1. config.json (copy from config.example.json), or"
+    echo "  2. Environment variables"
+    echo ""
+    echo "Required environment variables:"
+    echo "  - NEXTCLOUD_URL"
+    echo "  - NEXTCLOUD_USER"
+    echo "  - NEXTCLOUD_PASSWORD"
+    exit 1
+fi