Merge origin/main: resolve conflicts in FORK_SETUP.md, README.md, frontend/package.json

Made-with: Cursor

docs/misc/tools.func/README.md

@@ -75,7 +75,8 @@ Complete reference of environment variables and configuration options.
 ```bash
 setup_nodejs "20"     # Install Node.js v20
 setup_php "8.2"       # Install PHP 8.2
-setup_mariadb "11"    # Install MariaDB 11
+setup_mariadb         # Install MariaDB (distribution packages)
+# MARIADB_VERSION="11.4" setup_mariadb  # Specific version from official repo
 ```
 
 ### Safe Package Operations

docs/misc/tools.func/TOOLS_FUNC_FUNCTIONS_REFERENCE.md

@@ -20,14 +20,19 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_nodejs(VERSION)` - Install Node.js and npm
 - `setup_php(VERSION)` - Install PHP-FPM and CLI
 - `setup_python(VERSION)` - Install Python 3 with pip
+- `setup_uv()` - Install Python uv (modern & fast)
 - `setup_ruby(VERSION)` - Install Ruby with gem
 - `setup_golang(VERSION)` - Install Go programming language
+- `setup_java(VERSION)` - Install OpenJDK (Adoptium)
 
 **Databases**:
-- `setup_mariadb(VERSION)` - Install MariaDB server
+- `setup_mariadb()` - Install MariaDB server
+- `setup_mariadb_db()` - Create user/db in MariaDB
 - `setup_postgresql(VERSION)` - Install PostgreSQL
+- `setup_postgresql_db()` - Create user/db in PostgreSQL
 - `setup_mongodb(VERSION)` - Install MongoDB
 - `setup_redis(VERSION)` - Install Redis cache
+- `setup_meilisearch()` - Install Meilisearch engine
 
 **Web Servers**:
 - `setup_nginx()` - Install Nginx
@@ -44,6 +49,7 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 - `setup_docker_compose()` - Install Docker Compose
 - `setup_composer()` - Install PHP Composer
 - `setup_build_tools()` - Install build-essential
+- `setup_yq()` - Install mikefarah/yq processor
 
 **Monitoring**:
 - `setup_grafana()` - Install Grafana
@@ -60,13 +66,13 @@ Complete alphabetical reference of all functions in tools.func with parameters,
 
 ## Core Functions
 
-### pkg_install()
+### install_packages_with_retry()
 
-Install one or more packages safely with automatic retry logic and error handling.
+Install one or more packages safely with automatic retry logic (3 attempts), APT refresh, and lock handling.
 
 **Signature**:
 ```bash
-pkg_install PACKAGE1 [PACKAGE2 ...]
+install_packages_with_retry PACKAGE1 [PACKAGE2 ...]
 ```
 
 **Parameters**:
@@ -74,78 +80,136 @@ pkg_install PACKAGE1 [PACKAGE2 ...]
 
 **Returns**:
 - `0` - All packages installed successfully
-- `1` - Installation failed after retries
+- `1` - Installation failed after all retries
+
+**Features**:
+- Automatically sets `DEBIAN_FRONTEND=noninteractive`
+- Handles DPKG lock errors with `dpkg --configure -a`
+- Retries on transient network or APT failures
+
+**Example**:
+```bash
+install_packages_with_retry curl wget git
+```
+
+---
+
+### upgrade_packages_with_retry()
+
+Upgrades installed packages with the same robust retry logic as the installation helper.
+
+**Signature**:
+```bash
+upgrade_packages_with_retry
+```
+
+**Returns**:
+- `0` - Upgrade successful
+- `1` - Upgrade failed
+
+---
+
+### fetch_and_deploy_gh_release()
+
+The primary tool for downloading and installing software from GitHub Releases. Supports binaries, tarballs, and Debian packages.
+
+**Signature**:
+```bash
+fetch_and_deploy_gh_release APPREPO TYPE [VERSION] [DEST] [ASSET_PATTERN]
+```
 
 **Environment Variables**:
-- `$STD` - Output suppression (`silent` or empty)
+- `APPREPO`: GitHub repository (e.g., `owner/repo`)
+- `TYPE`: Asset type (`binary`, `tarball`, `prebuild`, `singlefile`)
+- `VERSION`: Specific tag or `latest` (Default: `latest`)
+- `DEST`: Target directory (Default: `/opt/$APP`)
+- `ASSET_PATTERN`: Regex or string pattern to match the release asset (Required for `prebuild` and `singlefile`)
+
+**Supported Operation Modes**:
+- `tarball`: Downloads and extracts the source tarball.
+- `binary`: Detects host architecture and installs a `.deb` package using `apt` or `dpkg`.
+- `prebuild`: Downloads and extracts a pre-built binary archive (supports `.tar.gz`, `.zip`, `.tgz`, `.txz`).
+- `singlefile`: Downloads a single binary file to the destination.
+
+**Environment Variables**:
+- `CLEAN_INSTALL=1`: Removes all contents of the destination directory before extraction.
+- `DPKG_FORCE_CONFOLD=1`: Forces `dpkg` to keep old config files during package updates.
+- `SYSTEMD_OFFLINE=1`: Used automatically for `.deb` installs to prevent systemd-tmpfiles failures in unprivileged containers.
 
 **Example**:
 ```bash
-pkg_install curl wget git
+fetch_and_deploy_gh_release "muesli/duf" "binary" "latest" "/opt/duf" "duf_.*_linux_amd64.tar.gz"
 ```
 
 ---
 
-### pkg_update()
+### check_for_gh_release()
 
-Update package lists with automatic retry logic for network failures.
+Checks if a newer version is available on GitHub compared to the installed version.
 
 **Signature**:
 ```bash
-pkg_update
+check_for_gh_release APP REPO
 ```
 
-**Parameters**: None
-
-**Returns**:
-- `0` - Package lists updated
-- `1` - Failed after 3 retries
-
 **Example**:
 ```bash
-pkg_update
+if check_for_gh_release "nodejs" "nodesource/distributions"; then
+  # update logic
+fi
 ```
 
 ---
 
-### pkg_remove()
+### prepare_repository_setup()
 
-Remove packages completely including dependencies.
+Performs safe repository preparation by cleaning up old files, keyrings, and ensuring the APT system is in a working state.
 
 **Signature**:
 ```bash
-pkg_remove PACKAGE1 [PACKAGE2 ...]
+prepare_repository_setup REPO_NAME [REPO_NAME2 ...]
 ```
 
-**Parameters**:
-- `PACKAGE1, PACKAGE2, ...` - Package names to remove
-
-**Returns**:
-- `0` - Packages removed
-- `1` - Removal failed
-
 **Example**:
 ```bash
-pkg_remove old-package outdated-tool
+prepare_repository_setup "mariadb" "mysql"
+```
+
+---
+
+### verify_tool_version()
+
+Validates if the installed major version matches the expected version.
+
+**Signature**:
+```bash
+verify_tool_version NAME EXPECTED INSTALLED
+```
+
+**Example**:
+```bash
+verify_tool_version "nodejs" "22" "$(node -v | grep -oP '^v\K[0-9]+')"
 ```
 
 ---
 
 ### setup_deb822_repo()
 
-Add repository in modern deb822 format (recommended over legacy format).
+Add repository in modern deb822 format.
 
 **Signature**:
 ```bash
-setup_deb822_repo REPO_URL NAME DIST MAIN_URL RELEASE
+setup_deb822_repo NAME GPG_URL REPO_URL SUITE COMPONENT [ARCHITECTURES] [ENABLED]
 ```
 
 **Parameters**:
-- `REPO_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
 - `NAME` - Repository name (e.g., "nodejs")
-- `DIST` - Distribution (jammy, bookworm, etc.)
-- `MAIN_URL` - Main repository URL
-- `RELEASE` - Release type (main, testing, etc.)
+- `GPG_URL` - URL to GPG key (e.g., https://example.com/key.gpg)
+- `REPO_URL` - Main repository URL (e.g., https://example.com/repo)
+- `SUITE` - Repository suite (e.g., "jammy", "bookworm")
+- `COMPONENT` - Repository component (e.g., "main", "testing")
+- `ARCHITECTURES` - Optional Comma-separated list of architectures (e.g., "amd64,arm64")
+- `ENABLED` - Optional "true" or "false" (default: "true")
 
 **Returns**:
 - `0` - Repository added successfully
@@ -154,10 +218,10 @@ setup_deb822_repo REPO_URL NAME DIST MAIN_URL RELEASE
 **Example**:
 ```bash
 setup_deb822_repo \
-  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
   "nodejs" \
+  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
+  "https://deb.nodesource.com/node_20.x" \  
   "jammy" \
-  "https://deb.nodesource.com/node_20.x" \
   "main"
 ```
 
@@ -186,12 +250,234 @@ cleanup_repo_metadata
 
 ## Tool Installation Functions
 
-### setup_nodejs(VERSION)
+### setup_nodejs()
 
-Install Node.js and npm from official repositories.
+Install Node.js and npm from official repositories. Handles legacy version cleanup (nvm) automatically.
 
 **Signature**:
 ```bash
+setup_nodejs
+```
+
+**Environment Variables**:
+- `NODE_VERSION`: Major version to install (e.g. "20", "22", "24"). Default: "24".
+- `NODE_MODULE`: Optional npm package to install globally during setup (e.g. "pnpm", "yarn").
+
+**Example**:
+```bash
+NODE_VERSION="22" NODE_MODULE="pnpm" setup_nodejs
+```
+
+---
+
+### setup_php()
+
+Install PHP with configurable extensions and FPM/Apache integration.
+
+**Signature**:
+```bash
+setup_php
+```
+
+**Environment Variables**:
+- `PHP_VERSION`: Version to install (e.g. "8.3", "8.4"). Default: "8.4".
+- `PHP_MODULE`: Comma-separated list of additional extensions.
+- `PHP_FPM`: Set to "YES" to install php-fpm.
+- `PHP_APACHE`: Set to "YES" to install libapache2-mod-php.
+
+**Example**:
+```bash
+PHP_VERSION="8.3" PHP_FPM="YES" PHP_MODULE="mysql,xml,zip" setup_php
+```
+
+---
+
+### setup_mariadb_db()
+
+Creates a new MariaDB database and a dedicated user with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
+
+**Environment Variables**:
+- `MARIADB_DB_NAME`: Name of the database (required)
+- `MARIADB_DB_USER`: Name of the database user (required)
+- `MARIADB_DB_PASS`: User password (optional, auto-generated if omitted)
+
+**Example**:
+```bash
+MARIADB_DB_NAME="myapp" MARIADB_DB_USER="myapp_user" setup_mariadb_db
+```
+
+---
+
+### setup_postgresql_db()
+
+Creates a new PostgreSQL database and a dedicated user/role with all privileges. Automatically generates a password if not provided and saves it to a credentials file.
+
+**Environment Variables**:
+- `PG_DB_NAME`: Name of the database (required)
+- `PG_DB_USER`: Name of the database user (required)
+- `PG_DB_PASS`: User password (optional, auto-generated if omitted)
+
+---
+
+### setup_java()
+
+Installs Temurin JDK.
+
+**Signature**:
+```bash
+JAVA_VERSION="21" setup_java
+```
+
+**Parameters**:
+- `JAVA_VERSION` - JDK version (e.g., "17", "21") (default: "21")
+
+**Example**:
+```bash
+JAVA_VERSION="17" setup_java
+```
+
+---
+
+### setup_uv()
+
+Installs `uv` (modern Python package manager).
+
+**Signature**:
+```bash
+PYTHON_VERSION="3.13" setup_uv
+```
+
+**Parameters**:
+- `PYTHON_VERSION` - Optional Python version to pre-install via uv (e.g., "3.12", "3.13")
+
+**Example**:
+```bash
+PYTHON_VERSION="3.13" setup_uv
+```
+
+---
+
+### setup_go()
+
+Installs Go programming language.
+
+**Signature**:
+```bash
+GO_VERSION="1.23" setup_go
+```
+
+**Parameters**:
+- `GO_VERSION` - Go version to install (default: "1.23")
+
+**Example**:
+```bash
+GO_VERSION="1.24" setup_go
+```
+
+---
+
+### setup_yq()
+
+Installs `yq` (YAML processor).
+
+**Signature**:
+```bash
+setup_yq
+```
+
+**Example**:
+```bash
+setup_yq
+```
+
+---
+
+### setup_composer()
+
+Installs PHP Composer.
+
+**Signature**:
+```bash
+setup_composer
+```
+
+**Example**:
+```bash
+setup_composer
+```
+
+---
+
+### setup_meilisearch()
+
+Install and configure Meilisearch search engine.
+
+**Environment Variables**:
+- `MEILISEARCH_BIND`: Address and port to bind to (Default: "127.0.0.1:7700")
+- `MEILISEARCH_ENV`: Environment mode (Default: "production")
+
+---
+
+### setup_yq()
+
+Install the `mikefarah/yq` YAML processor. Removes existing non-compliant versions.
+
+**Example**:
+```bash
+setup_yq
+yq eval '.app.version = "1.0.0"' -i config.yaml
+```
+
+---
+
+### setup_composer()
+
+Install or update the PHP Composer package manager. Handles `COMPOSER_ALLOW_SUPERUSER` automatically and performs self-updates if already installed.
+
+**Example**:
+```bash
+setup_php
+setup_composer
+$STD composer install --no-dev
+```
+
+---
+
+### setup_build_tools()
+
+Install the `build-essential` package suite for compiling software.
+
+---
+
+### setup_uv()
+
+Install the modern Python package manager `uv`. Extremely fast replacement for pip/venv.
+
+**Environment Variables**:
+- `PYTHON_VERSION`: Major.Minor version to ensure is installed.
+
+**Example**:
+```bash
+PYTHON_VERSION="3.12" setup_uv
+uv sync --locked
+```
+
+---
+
+### setup_java()
+
+Install OpenJDK via the Adoptium repository.
+
+**Environment Variables**:
+- `JAVA_VERSION`: Major version to install (e.g. "17", "21"). Default: "21".
+
+**Example**:
+```bash
+JAVA_VERSION="21" setup_java
+```
+
+---
+```bash
 setup_nodejs VERSION
 ```
 
@@ -238,17 +524,20 @@ setup_php "8.3"
 
 ---
 
-### setup_mariadb(VERSION)
+### setup_mariadb()
 
 Install MariaDB server and client utilities.
 
 **Signature**:
 ```bash
-setup_mariadb VERSION
+setup_mariadb                         # Uses distribution packages (recommended)
+MARIADB_VERSION="11.4" setup_mariadb  # Uses official MariaDB repository
 ```
 
-**Parameters**:
-- `VERSION` - MariaDB version (e.g., "10.6", "11.0")
+**Variables**:
+- `MARIADB_VERSION` - (optional) Specific MariaDB version
+  - Not set or `"latest"`: Uses distribution packages (most reliable, avoids mirror issues)
+  - Specific version (e.g., `"11.4"`, `"12.2"`): Uses official MariaDB repository
 
 **Returns**:
 - `0` - Installation successful
@@ -259,7 +548,11 @@ setup_mariadb VERSION
 
 **Example**:
 ```bash
-setup_mariadb "11.0"
+# Recommended: Use distribution packages (stable, no mirror issues)
+setup_mariadb
+
+# Specific version from official repository
+MARIADB_VERSION="11.4" setup_mariadb
 ```
 
 ---
@@ -441,7 +734,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 
 pkg_update                    # Update package lists
 setup_nodejs "20"             # Install Node.js
-setup_mariadb "11"            # Install MariaDB
+setup_mariadb                 # Install MariaDB (distribution packages)
 
 # ... application installation ...
 
@@ -460,7 +753,7 @@ source /dev/stdin <<<"$FUNCTIONS_FILE_PATH"
 pkg_update
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages
 setup_composer
 ```
 

docs/misc/tools.func/TOOLS_FUNC_USAGE_EXAMPLES.md

@@ -65,7 +65,7 @@ pkg_update
 
 setup_nginx
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Uses distribution packages (recommended)
 setup_composer
 
 msg_ok "Web stack installed"
@@ -221,10 +221,10 @@ msg_info "Setting up repository"
 
 # Add custom repository in deb822 format
 setup_deb822_repo \
-  "https://my-repo.example.com/gpg.key" \
   "my-applications" \
-  "jammy" \
+  "https://my-repo.example.com/gpg.key" \
   "https://my-repo.example.com/debian" \
+  "jammy" \
   "main"
 
 msg_ok "Repository configured"
@@ -244,18 +244,18 @@ msg_info "Setting up repositories"
 
 # Node.js repository
 setup_deb822_repo \
-  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
   "nodejs" \
-  "jammy" \
+  "https://deb.nodesource.com/gpgkey/nodesource.gpg.key" \
   "https://deb.nodesource.com/node_20.x" \
+  "jammy" \
   "main"
 
 # Docker repository
 setup_deb822_repo \
-  "https://download.docker.com/linux/ubuntu/gpg" \
   "docker" \
-  "jammy" \
+  "https://download.docker.com/linux/ubuntu/gpg" \
   "https://download.docker.com/linux/ubuntu" \
+  "jammy" \
   "stable"
 
 # Update once for all repos
@@ -388,7 +388,7 @@ pkg_install package-name
 # Chain multiple tools together
 setup_nodejs "20"
 setup_php "8.3"
-setup_mariadb "11"
+setup_mariadb  # Distribution packages (recommended)
 
 # Check command success
 if ! setup_docker; then