From 6cd0d5333ac1cf09bd19594909ff128a46544697 Mon Sep 17 00:00:00 2001 From: Godopu Date: Tue, 23 Jun 2026 08:22:41 +0900 Subject: [PATCH] feat(deploy): add Gitea deployment templates, installer, and CI/CD workflow --- deploy/README.md | 52 ++++++++++++++++++ deploy/gitea-ci.yml | 70 +++++++++++++++++++++++++ deploy/install.sh | 125 ++++++++++++++++++++++++++++++++++++++++++++ deploy/plugin.json | 5 ++ 4 files changed, 252 insertions(+) create mode 100644 deploy/README.md create mode 100644 deploy/gitea-ci.yml create mode 100644 deploy/install.sh create mode 100644 deploy/plugin.json diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..79390ab --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,52 @@ +# 🚀 Multi-Agent Mux (MAM) Deployment & Gitea Integration + +This directory contains packaging templates and installation scripts to deploy the **Multi-Agent Mux** framework into workspaces hosted on **Gitea** (or GitHub). + +--- + +## 📁 Deployment Directory Structure + +* **`install.sh`**: A self-contained, idempotent shell installer that checks system requirements (`tmux`, `python3`, `pip3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`). +* **`plugin.json`**: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms (such as Claude Code, Antigravity, or other TUI clients). +* **`gitea-ci.yml`**: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting on bash scripts, validation on python scripts, and compilation tests). + +--- + +## đŸ“Ļ How to Install and Deploy + +### 1. Simple One-Liner Installation (from Gitea repository) +Once you push this repository to your Gitea instance, users can install it in their local workspace directory by running: + +```bash +curl -fsSL https:////multi-agent-mux/raw/branch/main/deploy/install.sh | bash +``` + +Alternatively, if they have cloned the repository, they can execute: +```bash +bash deploy/install.sh +``` + +### 2. Registering as a Workspace Plugin +To register these skills globally or for a specific workspace: +* **Workspace Level**: Copy the `.agents/` folder into your project root. +* **Global Level (Gemini/Antigravity)**: Register the plugin path in your global config file at `~/.gemini/config/skills.json`: + ```json + { + "entries": [ + { "path": "/absolute/path/to/multi-agent-mux/.agents/skills" } + ] + } + ``` + +--- + +## 🤖 Gitea Actions CI/CD Setup + +To automate testing and script linting on your Gitea repository: +1. Ensure Gitea Actions is enabled on your Gitea instance. +2. Copy the Gitea CI workflow to your workspace's workflow folder: + ```bash + mkdir -p .gitea/workflows + cp deploy/gitea-ci.yml .gitea/workflows/ci.yml + ``` +3. Commit and push to your Gitea repository. The pipeline will validate shell syntax and python file compilation on every push to `main` and pull requests. diff --git a/deploy/gitea-ci.yml b/deploy/gitea-ci.yml new file mode 100644 index 0000000..394dd82 --- /dev/null +++ b/deploy/gitea-ci.yml @@ -0,0 +1,70 @@ +# ============================================================================== +# Gitea Actions CI/CD Workflow Template +# ============================================================================== +# Place this file in '.gitea/workflows/ci.yml' or use it directly in Gitea's CI. +# It automatically validates shell scripts and checks Python formatting/syntax. +# ============================================================================== +name: Multi-Agent Mux CI + +on: + push: + branches: [ main, dev ] + pull_request: + branches: [ main ] + +jobs: + lint-shell: + name: Lint Shell Scripts + runs-on: ubuntu-latest + steps: + - name: Checkout Code + uses: actions/checkout@v3 + + - name: Install ShellCheck + run: | + sudo apt-get update + sudo apt-get install -y shellcheck + + - name: Run ShellCheck + run: | + echo "🔍 Linting shell scripts..." + shellcheck .agents/skills/lib.sh + shellcheck .agents/skills/multi-agent-mux-create/scripts/create_session.sh + shellcheck .agents/skills/multi-agent-mux-stop/scripts/stop_session.sh + shellcheck .agents/skills/multi-agent-mux-monitor/scripts/reconcile.sh + shellcheck deploy/install.sh + echo "✅ ShellCheck completed successfully." + + lint-python: + name: Lint Python Backplane + runs-on: ubuntu-latest + steps: + - name: Checkout Code + uses: actions/checkout@v3 + + - name: Set up Python + uses: actions/setup-python@v4 + with: + python-version: '3.10' + cache: 'pip' + + - name: Install Dependencies + run: | + python -m pip install --upgrade pip + pip install flake8 pylint + if [ -f .agents/skills/multi-agent-mux-delegate-job/requirements.txt ]; then + pip install -r .agents/skills/multi-agent-mux-delegate-job/requirements.txt + fi + + - name: Run Flake8 (Syntax/Error Check) + run: | + echo "🔍 Checking Python syntax with flake8..." + flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --select=E9,F63,F7,F82 --show-source --statistics + # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide + flake8 .agents/skills/multi-agent-mux-delegate-job/scripts/ --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + + - name: Run Python Syntax Check (Compile test) + run: | + echo "🔍 Verifying Python file compilation..." + python -m py_compile .agents/skills/multi-agent-mux-delegate-job/scripts/*.py + echo "✅ All Python files compiled successfully." diff --git a/deploy/install.sh b/deploy/install.sh new file mode 100644 index 0000000..15fe3b6 --- /dev/null +++ b/deploy/install.sh @@ -0,0 +1,125 @@ +#!/usr/bin/env bash +# ============================================================================== +# install.sh — Multi-Agent Mux (MAM) Orchestration Installer +# ============================================================================== +# Idempotent, robust installer to bootstrap MAM orchestration skills +# and Python backplane dependencies on any local workspace. +# ============================================================================== +set -euo pipefail + +# --- Configuration & Defaults --- +TARGET_DIR="${1:-$(pwd)}" +VENV_NAME=".venv" +MIN_PYTHON_VERSION="3.9" + +echo "====================================================================" +echo "⚡ Starting Multi-Agent Mux (MAM) Installation" +echo "📂 Target Workspace: $TARGET_DIR" +echo "====================================================================" + +# --- 1. System Requirements Validation --- +echo "🔍 Checking system dependencies..." + +check_cmd() { + local cmd="$1" + if ! command -v "$cmd" &>/dev/null; then + echo "❌ Error: '$cmd' is not installed. Please install it first." >&2 + exit 1 + fi +} + +check_cmd tmux +check_cmd python3 +check_cmd pip3 + +# Verify Python Version +PYTHON_VERSION=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")') +if python3 -c "import sys; exit(0 if sys.version_info >= (3, 9) else 1)"; then + echo "✅ Python $PYTHON_VERSION detected." +else + echo "❌ Error: Python version must be $MIN_PYTHON_VERSION or higher. Detected: $PYTHON_VERSION" >&2 + exit 1 +fi + +# --- 2. Workspace Setup --- +cd "$TARGET_DIR" +echo "📂 Ensuring metadata directory structure (.mam/)..." +mkdir -p .mam/jobs .mam/delegate_job_logs + +# File permission lockdown on database directory +chmod 0700 .mam + +# --- 3. Check Network File System (NFS) Warnings --- +echo "💾 Detecting file system mount type..." +if command -v df &>/dev/null && command -v mount &>/dev/null; then + MOUNTPOINT="$(df --output=target . 2>/dev/null | tail -1 || echo "")" + if [ -n "$MOUNTPOINT" ]; then + if mount | grep -q "$MOUNTPOINT.*nfs\|$MOUNTPOINT.*cifs\|$MOUNTPOINT.*fuse.sshfs"; then + echo "⚠ī¸ WARNING: Target directory is on a network filesystem (NFS/CIFS/SSHFS)." + echo " File locks (fcntl.flock) are UNRELIABLE on network storage." + echo " The sqlite3 registry will fall back to 'DELETE' journaling instead of WAL." + else + echo "✅ File system supports WAL (Local storage detected)." + fi + fi +fi + +# --- 4. Python Virtual Environment Setup --- +echo "🐍 Bootstrapping Python virtual environment (.venv)..." +if [ ! -d "$VENV_NAME" ]; then + python3 -m venv "$VENV_NAME" + echo "✅ Virtual environment created." +else + echo "ℹī¸ Virtual environment (.venv) already exists. Skipping creation." +fi + +# Activate virtual environment +# shellcheck disable=SC1091 +source "$VENV_NAME"/bin/activate + +# Install requirements +REQ_FILE=".agents/skills/multi-agent-mux-delegate-job/requirements.txt" +if [ -f "$REQ_FILE" ]; then + echo "đŸ“Ļ Installing backplane dependencies from $REQ_FILE..." + pip install --upgrade pip + pip install -r "$REQ_FILE" + echo "✅ Dependencies installed successfully." +else + echo "⚠ī¸ WARNING: Could not find requirements file: $REQ_FILE" + echo " Installing default packages (paho-mqtt, pyyaml) manually..." + pip install --upgrade pip + pip install "paho-mqtt>=2.0.0" pyyaml +fi + +# --- 5. Generate Environment Template --- +ENV_FILE=".env" +ENV_EXAMPLE=".env.example" +if [ ! -f "$ENV_FILE" ]; then + if [ -f "$ENV_EXAMPLE" ]; then + echo "📝 Creating configuration from $ENV_EXAMPLE..." + cp "$ENV_EXAMPLE" "$ENV_FILE" + chmod 0600 "$ENV_FILE" + else + echo "📝 Creating default $ENV_FILE..." + cat < "$ENV_FILE" +# ============================================================================== +# Multi-Agent Mux (MAM) Environment Settings +# ============================================================================== +MQTT_BROKER=broker.hivemq.com +MQTT_PORT=1883 +MQTT_TLS=0 +MQTT_CLIENT_ID_PREFIX=mam-agent +TMUX_SERVER_NAME=default +EOF + chmod 0600 "$ENV_FILE" + fi + echo "✅ Config file .env initialized with chmod 0600." +else + echo "ℹī¸ $ENV_FILE already exists. Skipping config override." +fi + +echo "====================================================================" +echo "🎉 Installation complete!" +echo "✨ You can now run the status or monitor skills." +echo "💡 Hint: Try executing: .venv/bin/python .agents/skills/multi-agent-mux-delegate-job/scripts/registry.py list" +echo "====================================================================" diff --git a/deploy/plugin.json b/deploy/plugin.json new file mode 100644 index 0000000..87a7aee --- /dev/null +++ b/deploy/plugin.json @@ -0,0 +1,5 @@ +{ + "name": "multi-agent-mux", + "description": "Multi-Agent Orchestration & Messaging Backplane on Tmux & MQTT.", + "disabled": false +}