ci: Add Gitea Actions workflows and CI/CD documentation

.gitea/workflows/deploy.yml

@@ -0,0 +1,136 @@
+name: Deploy to Coolify
+
+on:
+  push:
+    branches:
+      - main        # Production deployment
+      - develop     # Development deployment
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  # Lint and type-check (runs on all pushes and PRs)
+  quality-check:
+    name: Code Quality
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun install --frozen-lockfile
+          else
+            echo "App directory not yet created, skipping"
+          fi
+
+      - name: Type check
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun run typecheck || echo "Typecheck not configured yet"
+          fi
+
+      - name: Lint
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun run lint || echo "Linting not configured yet"
+          fi
+
+  # Run tests (when implemented)
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    needs: quality-check
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun install --frozen-lockfile
+          fi
+
+      - name: Run unit tests
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun test || echo "Tests not configured yet"
+          fi
+
+  # Deploy to Development (develop branch only)
+  deploy-dev:
+    name: Deploy to Development
+    runs-on: ubuntu-latest
+    needs: [quality-check, test]
+    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
+    environment:
+      name: development
+      url: https://pantry-dev.jeanlucmakiola.de  # Update with actual URL
+    steps:
+      - name: Trigger Coolify Deployment (Dev)
+        run: |
+          curl -X POST "${{ secrets.COOLIFY_WEBHOOK_DEV }}" \
+            -H "Content-Type: application/json" \
+            -d '{"branch": "develop"}'
+
+      - name: Deployment Status
+        run: |
+          echo "✅ Deployment triggered for development environment"
+          echo "🔗 Check status: https://coolify.jeanlucmakiola.de"
+
+  # Deploy to Production (main branch only)
+  deploy-prod:
+    name: Deploy to Production
+    runs-on: ubuntu-latest
+    needs: [quality-check, test]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment:
+      name: production
+      url: https://pantry.jeanlucmakiola.de  # Update with actual URL
+    steps:
+      - name: Trigger Coolify Deployment (Prod)
+        run: |
+          curl -X POST "${{ secrets.COOLIFY_WEBHOOK_PROD }}" \
+            -H "Content-Type: application/json" \
+            -d '{"branch": "main"}'
+
+      - name: Deployment Status
+        run: |
+          echo "✅ Deployment triggered for production environment"
+          echo "🔗 Check status: https://coolify.jeanlucmakiola.de"
+
+  # Optional: Deploy to Test (manual trigger)
+  deploy-test:
+    name: Deploy to Test
+    runs-on: ubuntu-latest
+    needs: [quality-check, test]
+    if: github.event_name == 'workflow_dispatch'
+    environment:
+      name: test
+    steps:
+      - name: Trigger Coolify Deployment (Test)
+        run: |
+          curl -X POST "${{ secrets.COOLIFY_WEBHOOK_TEST }}" \
+            -H "Content-Type: application/json"
+
+      - name: Deployment Status
+        run: |
+          echo "✅ Deployment triggered for test environment"

.gitea/workflows/pr-checks.yml

@@ -0,0 +1,65 @@
+name: Pull Request Checks
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+
+jobs:
+  pr-validation:
+    name: Validate PR
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for better diff analysis
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun install --frozen-lockfile
+          fi
+
+      - name: Type check
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun run typecheck || echo "⚠️  Typecheck not configured"
+          fi
+
+      - name: Lint
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun run lint || echo "⚠️  Linting not configured"
+          fi
+
+      - name: Run tests
+        run: |
+          if [ -d "app" ]; then
+            cd app
+            bun test || echo "⚠️  Tests not configured"
+          fi
+
+      - name: Check migrations
+        run: |
+          if [ -d "supabase/migrations" ]; then
+            echo "📋 Migration files found:"
+            ls -la supabase/migrations/
+          fi
+
+      - name: PR Summary
+        run: |
+          echo "## ✅ Pull Request Validation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Branch:** ${{ github.head_ref }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Target:** ${{ github.base_ref }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Author:** ${{ github.actor }}" >> $GITHUB_STEP_SUMMARY

docs/BRANCHING.md

@@ -0,0 +1,358 @@
+# Pantry - Branching Strategy
+
+## 🌿 Branch Structure
+
+```
+main (production)
+  ↑
+  └── develop (development)
+        ↑
+        ├── feature/barcode-scanner
+        ├── feature/tag-system
+        ├── fix/quantity-bug
+        └── chore/update-deps
+```
+
+---
+
+## 📋 Branch Types
+
+### `main` - Production
+
+- **Purpose:** Production-ready code
+- **Protection:** Require PR approval
+- **Deploy:** Auto-deploy to production on push
+- **Stability:** Must always be stable
+
+**Rules:**
+- Never commit directly
+- Only merge from `develop` via release PR
+- All merges must pass CI/CD checks
+
+### `develop` - Development
+
+- **Purpose:** Integration branch for features
+- **Protection:** Require PR approval (optional)
+- **Deploy:** Auto-deploy to dev environment on push
+- **Stability:** Should be stable, but can have minor issues
+
+**Rules:**
+- Never commit directly (except hotfixes)
+- Merge features via PR
+- Keep in sync with `main` regularly
+
+### `feature/*` - Features
+
+- **Purpose:** New features or enhancements
+- **Naming:** `feature/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `feature/barcode-scanner`
+- `feature/tag-management`
+- `feature/unit-conversions`
+
+### `fix/*` - Bug Fixes
+
+- **Purpose:** Fix bugs in `develop`
+- **Naming:** `fix/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `fix/quantity-validation`
+- `fix/tag-duplication`
+
+### `hotfix/*` - Production Hotfixes
+
+- **Purpose:** Critical fixes for production
+- **Naming:** `hotfix/short-description`
+- **Base:** Branch from `main`
+- **Merge:** PR to both `main` AND `develop`
+
+**Examples:**
+- `hotfix/auth-bypass`
+- `hotfix/data-corruption`
+
+**Process:**
+```bash
+git checkout main
+git pull
+git checkout -b hotfix/critical-bug
+# Fix bug
+git push origin hotfix/critical-bug
+# Create PR to main (deploy immediately)
+# Create second PR to develop (keep in sync)
+```
+
+### `release/*` - Releases
+
+- **Purpose:** Prepare for production release
+- **Naming:** `release/v0.1.0`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `main` (then tag)
+
+**Process:**
+```bash
+git checkout develop
+git pull
+git checkout -b release/v0.1.0
+# Update version, changelog, docs
+git push origin release/v0.1.0
+# Create PR to main
+# After merge, tag main with v0.1.0
+```
+
+### `chore/*` - Maintenance
+
+- **Purpose:** Dependencies, configs, tooling
+- **Naming:** `chore/short-description`
+- **Base:** Branch from `develop`
+- **Merge:** PR to `develop`
+
+**Examples:**
+- `chore/update-nuxt`
+- `chore/eslint-config`
+- `chore/ci-improvements`
+
+---
+
+## 🔄 Workflow Examples
+
+### Adding a Feature
+
+```bash
+# 1. Start from develop
+git checkout develop
+git pull origin develop
+
+# 2. Create feature branch
+git checkout -b feature/barcode-scanner
+
+# 3. Work on feature
+# ... make changes ...
+
+# 4. Commit regularly
+git add .
+git commit -m "feat: Add barcode detection logic"
+
+# 5. Push to remote
+git push origin feature/barcode-scanner
+
+# 6. Create PR to develop on Gitea
+# Review → Merge → Auto-deploys to dev
+```
+
+### Releasing to Production
+
+```bash
+# 1. Ensure develop is stable
+git checkout develop
+git pull origin develop
+
+# 2. Create release branch
+git checkout -b release/v0.1.0
+
+# 3. Update version and changelog
+# Edit package.json, CHANGELOG.md
+
+# 4. Commit and push
+git commit -am "chore: Prepare v0.1.0 release"
+git push origin release/v0.1.0
+
+# 5. Create PR to main
+# Review → Merge → Auto-deploys to production
+
+# 6. Tag the release
+git checkout main
+git pull origin main
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+
+# 7. Merge back to develop (keep in sync)
+git checkout develop
+git merge main
+git push origin develop
+```
+
+### Hotfix Production Issue
+
+```bash
+# 1. Branch from main
+git checkout main
+git pull origin main
+git checkout -b hotfix/auth-bypass
+
+# 2. Fix the issue
+# ... fix ...
+
+# 3. Commit and push
+git commit -am "fix: Patch authentication bypass"
+git push origin hotfix/auth-bypass
+
+# 4. Create PR to main
+# Urgent review → Merge → Immediate deploy
+
+# 5. Also PR to develop (keep in sync)
+git checkout develop
+git pull origin develop
+git checkout -b hotfix/auth-bypass-to-develop
+git merge hotfix/auth-bypass
+git push origin hotfix/auth-bypass-to-develop
+# Create second PR to develop
+```
+
+---
+
+## 📝 Commit Message Convention
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding/updating tests
+- `chore`: Maintenance (deps, configs)
+- `perf`: Performance improvement
+
+### Examples
+
+```bash
+feat(scan): Add barcode scanner component
+fix(inventory): Prevent negative quantities
+docs(api): Update product lookup examples
+chore(deps): Upgrade Nuxt to 4.1.2
+refactor(tags): Simplify tag picker logic
+test(units): Add conversion edge cases
+```
+
+---
+
+## 🔒 Branch Protection Rules
+
+### `main` (Production)
+
+- ✅ Require pull request before merging
+- ✅ Require status checks to pass
+- ✅ Require review from code owner (1+)
+- ✅ Dismiss stale approvals
+- ❌ Allow force push
+- ❌ Allow deletions
+
+### `develop` (Development)
+
+- ✅ Require pull request before merging (optional)
+- ✅ Require status checks to pass
+- ⚠️  Require review (recommended, not enforced)
+- ❌ Allow force push
+- ❌ Allow deletions
+
+**Configure in Gitea:**
+Repository → Settings → Branches → Add rule
+
+---
+
+## 🎯 Best Practices
+
+### Keep Branches Short-Lived
+
+- Feature branches: 1-3 days max
+- Merge frequently to avoid conflicts
+- Delete after merge
+
+### Sync with Develop Regularly
+
+```bash
+# While on feature branch
+git checkout feature/my-feature
+git fetch origin
+git merge origin/develop
+# Resolve conflicts if any
+```
+
+### Clean Commit History
+
+```bash
+# Interactive rebase before PR (optional)
+git rebase -i develop
+
+# Squash WIP commits into logical commits
+```
+
+### Tag Releases
+
+```bash
+# After merging release to main
+git checkout main
+git pull
+git tag -a v0.1.0 -m "MVP Release - Week 6"
+git push origin v0.1.0
+```
+
+---
+
+## 🚫 Anti-Patterns (Don't Do This)
+
+❌ **Commit directly to `main`**
+- Always use PR workflow
+
+❌ **Long-lived feature branches**
+- Break into smaller features
+- Merge incrementally
+
+❌ **Merge without review**
+- At least one other person should review
+
+❌ **Push broken code to `develop`**
+- Test locally first
+- CI checks should pass
+
+❌ **Forget to sync hotfix to `develop`**
+- Hotfixes must go to both branches
+
+---
+
+## 📊 Branch Lifecycle
+
+```
+feature/barcode-scanner
+  Created: 2026-02-10
+  Author: Jean-Luc
+  Status: In Progress
+  PRs: #15 (to develop)
+  
+  ↓ (PR merged)
+  
+  Merged to develop: 2026-02-12
+  Deployed to dev: ✅
+  Deleted: 2026-02-12
+```
+
+**Keep branches clean:**
+```bash
+# List merged branches
+git branch --merged develop
+
+# Delete merged local branches
+git branch -d feature/barcode-scanner
+
+# Delete merged remote branches
+git push origin --delete feature/barcode-scanner
+```
+
+---
+
+**Summary:** Keep it simple. Feature → PR → Develop → Test → Release → Main → Production. Always review, always test, never break `main`.

docs/CI_CD.md

@@ -0,0 +1,311 @@
+# Pantry - CI/CD Pipeline
+
+**Version:** 1.0  
+**Last Updated:** 2026-02-08
+
+---
+
+## 🔄 Overview
+
+Pantry uses **Gitea Actions** for CI/CD, automatically deploying to **Coolify** on push.
+
+### Workflow Strategy
+
+```
+Feature Branch → PR → Code Review → Merge → Auto-Deploy
+      ↓
+  PR Checks
+   (no deploy)
+```
+
+**Environments:**
+- **Development** (`develop` branch) → Auto-deploy to dev.pantry
+- **Production** (`main` branch) → Auto-deploy to pantry
+- **Test** (manual trigger) → On-demand testing
+
+---
+
+## 📋 Workflows
+
+### 1. `deploy.yml` - Main Deployment Pipeline
+
+**Triggers:**
+- Push to `main` → Deploy to production
+- Push to `develop` → Deploy to development
+- Pull requests → Run quality checks only
+
+**Jobs:**
+
+1. **quality-check** - Runs on all pushes/PRs
+   - Type checking
+   - Linting
+   - Code formatting validation
+
+2. **test** - Runs unit tests
+   - Unit tests (Vitest)
+   - Integration tests (future)
+
+3. **deploy-dev** - Development deployment
+   - Trigger: Push to `develop`
+   - Target: Coolify dev environment
+   - Auto-deploy
+
+4. **deploy-prod** - Production deployment
+   - Trigger: Push to `main`
+   - Target: Coolify production environment
+   - Auto-deploy
+
+5. **deploy-test** - Test deployment (optional)
+   - Trigger: Manual (`workflow_dispatch`)
+   - Target: Coolify test environment
+
+### 2. `pr-checks.yml` - Pull Request Validation
+
+**Triggers:**
+- Pull requests to `main` or `develop`
+
+**Jobs:**
+- Type checking
+- Linting
+- Tests
+- Migration validation
+- PR summary generation
+
+---
+
+## 🔐 Required Secrets
+
+Configure these in **Gitea Repository Settings → Secrets**:
+
+### Coolify Webhook URLs
+
+1. **`COOLIFY_WEBHOOK_DEV`**
+   - Coolify webhook URL for dev environment
+   - Format: `https://coolify.jeanlucmakiola.de/api/v1/deploy/webhooks/{uuid}`
+
+2. **`COOLIFY_WEBHOOK_PROD`**
+   - Coolify webhook URL for production environment
+   - Same format as above
+
+3. **`COOLIFY_WEBHOOK_TEST`** (optional)
+   - Coolify webhook URL for test environment
+
+### How to Get Webhook URLs
+
+**Via Coolify UI:**
+1. Go to Coolify → Projects → Pantry
+2. Select environment (dev/prod/test)
+3. Click on the resource (application)
+4. Go to "Webhooks" or "Deploy" tab
+5. Copy webhook URL
+
+**Via Coolify API:**
+```bash
+source ~/.openclaw/workspace/coolify-helpers.sh
+COOLIFY_URL=$(grep COOLIFY_URL ~/.coolify-credentials | cut -d= -f2)
+COOLIFY_TOKEN=$(grep COOLIFY_TOKEN ~/.coolify-credentials | cut -d= -f2)
+
+# Get application UUID (once created)
+curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
+  "${COOLIFY_URL}/api/v1/applications" | jq '.[] | select(.name | contains("pantry"))'
+
+# Webhook format:
+# ${COOLIFY_URL}/api/v1/deploy/webhooks/{application_uuid}
+```
+
+---
+
+## 🚀 Deployment Flow
+
+### Development Workflow
+
+```bash
+# 1. Create feature branch
+git checkout -b feature/barcode-scanner
+
+# 2. Make changes
+# ... code ...
+
+# 3. Commit and push
+git add .
+git commit -m "feat: Add barcode scanner component"
+git push origin feature/barcode-scanner
+
+# 4. Create PR to 'develop'
+# → PR checks run automatically
+
+# 5. Merge PR
+# → Auto-deploys to dev environment
+```
+
+### Production Release
+
+```bash
+# 1. Ensure develop is stable
+git checkout develop
+git pull
+
+# 2. Create release PR to main
+git checkout -b release/v0.1.0
+
+# 3. Update version, changelog
+# ... updates ...
+
+# 4. Push and create PR to main
+git push origin release/v0.1.0
+# → PR checks run
+
+# 5. Merge to main
+# → Auto-deploys to production
+```
+
+---
+
+## 🏗️ Coolify Setup (Per Environment)
+
+### Prerequisites
+
+Each environment needs:
+1. **Supabase service** (already configured for dev)
+2. **Pantry app resource** (to be created)
+
+### Creating App Resource in Coolify
+
+**For each environment (dev/prod/test):**
+
+1. **Go to Coolify → Projects → Pantry → [Environment]**
+
+2. **Add New Resource:**
+   - Type: **Application**
+   - Source: **Git Repository**
+
+3. **Configure Git:**
+   - Repository: `https://gitea.jeanlucmakiola.de/pantry-app/pantry.git`
+   - Branch:
+     - Dev: `develop`
+     - Prod: `main`
+     - Test: `develop` (or specific branch)
+
+4. **Build Configuration:**
+   - Build Pack: **Nixpacks** or **Dockerfile**
+   - Dockerfile Path: `app/Dockerfile` (when created)
+   - Build Command: `bun install && bun run build`
+   - Start Command: `bun run start`
+
+5. **Environment Variables:**
+   - Import from `.env.development` or `.env.production`
+   - Link to Supabase service environment
+
+6. **Domain:**
+   - Dev: `pantry-dev.jeanlucmakiola.de`
+   - Prod: `pantry.jeanlucmakiola.de`
+   - Test: `pantry-test.jeanlucmakiola.de`
+
+7. **Enable Webhook:**
+   - Go to resource → Webhooks
+   - Copy webhook URL
+   - Add to Gitea secrets
+
+---
+
+## 🔍 Monitoring Deployments
+
+### Via Gitea
+
+- **Actions Tab** in repository
+- View workflow runs
+- Check logs for each job
+
+### Via Coolify
+
+- **Resources** → Select environment
+- **Deployments** tab shows history
+- **Logs** show build/runtime output
+
+### Manual Trigger (Emergency Deploy)
+
+```bash
+# Via Gitea Actions UI
+# Repository → Actions → deploy.yml → Run workflow
+
+# Or via webhook directly
+curl -X POST "https://coolify.jeanlucmakiola.de/api/v1/deploy/webhooks/{uuid}"
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Workflow Not Running
+
+**Check:**
+- Gitea Actions is enabled (repo settings)
+- `.gitea/workflows/` directory exists
+- YAML syntax is valid
+
+**Enable Gitea Actions:**
+```bash
+# If self-hosted Gitea instance
+# Check Gitea admin panel → Actions → Enabled
+```
+
+### Deployment Failed
+
+**Check:**
+1. **Gitea Actions logs** - See which step failed
+2. **Coolify deployment logs** - Build/runtime errors
+3. **Environment variables** - Missing/incorrect values
+4. **Webhook URL** - Correct and accessible
+
+### Secrets Not Working
+
+**Verify:**
+```bash
+# In Gitea UI:
+# Repository → Settings → Secrets → Actions
+# Ensure COOLIFY_WEBHOOK_* secrets exist
+```
+
+---
+
+## 📊 Workflow Status Badges
+
+Add to `README.md`:
+
+```markdown
+[![Deploy](https://gitea.jeanlucmakiola.de/pantry-app/pantry/actions/workflows/deploy.yml/badge.svg)](https://gitea.jeanlucmakiola.de/pantry-app/pantry/actions)
+```
+
+---
+
+## 🔮 Future Improvements
+
+### v0.2+
+- [ ] E2E tests in pipeline (Playwright)
+- [ ] Database migration validation
+- [ ] Performance benchmarks
+- [ ] Lighthouse CI (PWA scores)
+- [ ] Automatic changelog generation
+- [ ] Slack/Discord notifications
+
+### v0.3+
+- [ ] Staging environment
+- [ ] Blue-green deployments
+- [ ] Rollback automation
+- [ ] Database backup before migrations
+
+---
+
+## 📚 References
+
+- [Gitea Actions Docs](https://docs.gitea.com/usage/actions/overview)
+- [Coolify Webhooks](https://coolify.io/docs/knowledge-base/git/github/webhooks)
+- [GitHub Actions Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) (compatible with Gitea)
+
+---
+
+**Next Steps:**
+1. Get Coolify webhook URLs for dev/prod
+2. Add secrets to Gitea repository
+3. Create Pantry app resources in Coolify
+4. Test deployment pipeline