From eb733cf7c130b62cbfaee5882aed98c1f628d8be Mon Sep 17 00:00:00 2001 From: Godopu Date: Sun, 12 Jul 2026 16:22:06 +0900 Subject: [PATCH] refactor(deploy): consolidate install scripts and INSTALL.md into deploy/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Move scripts/install_mam.sh → deploy/install_mam.sh (local-clone installer) - Move scripts/generate-env.sh → deploy/generate-env.sh (env helper) - Move .agents/INSTALL.md → deploy/INSTALL.md (user manual) - Update install_mam.sh to copy INSTALL.md + generate-env.sh from new paths - Ship INSTALL.md via deploy/install.sh remote path too (manifest-tracked) - Update README/BOOTSTRAP generate-env.sh references & repository ASCII layout - Extend deploy/README.md structure section; extend gitea-ci.yml lint list - Remove now-empty scripts/ directory - Fix duplicate ### 2. subsection headers in deploy/README.md (address B-2) - Correct deploy/INSTALL.md dependency description to match actual checks (address M-1) - Add local-clone lifecycle caveat (no update.sh/remove.sh) (address M-2) Closes the deploy consolidation plan and addresses Planner / Reviewer feedback. --- BOOTSTRAP.ko.md | 4 ++-- BOOTSTRAP.md | 4 ++-- README.ko.md | 11 ++++++++--- README.md | 11 ++++++++--- {.agents => deploy}/INSTALL.md | 10 +++++----- deploy/README.md | 19 ++++++++++++++++--- {scripts => deploy}/generate-env.sh | 4 ++-- deploy/gitea-ci.yml | 4 ++++ deploy/install.sh | 9 +++++++++ {scripts => deploy}/install_mam.sh | 11 ++++++++--- 10 files changed, 64 insertions(+), 23 deletions(-) rename {.agents => deploy}/INSTALL.md (88%) rename {scripts => deploy}/generate-env.sh (95%) rename {scripts => deploy}/install_mam.sh (94%) diff --git a/BOOTSTRAP.ko.md b/BOOTSTRAP.ko.md index 326c999..99d9880 100644 --- a/BOOTSTRAP.ko.md +++ b/BOOTSTRAP.ko.md @@ -58,10 +58,10 @@ curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/in ```bash # .env.example를 .env로 자동 복제 (이미 존재하면 덮어쓰지 않고 보호됨) -./scripts/generate-env.sh +./deploy/generate-env.sh # 만약 강제로 덮어쓰고 백업을 생성하고 싶은 경우: -./scripts/generate-env.sh --force +./deploy/generate-env.sh --force ``` ### 단계 3.2: 환경 변수 수정 및 설정 diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md index 7934155..277a725 100644 --- a/BOOTSTRAP.md +++ b/BOOTSTRAP.md @@ -58,10 +58,10 @@ Run the environment template copy script provided in the project root: ```bash # Automatically copy .env.example to .env (does not overwrite if it already exists) -./scripts/generate-env.sh +./deploy/generate-env.sh # To force overwrite and create a backup of the existing .env: -./scripts/generate-env.sh --force +./deploy/generate-env.sh --force ``` ### Step 3.2: Modify Environment Variables diff --git a/README.ko.md b/README.ko.md index a920c36..098f73b 100644 --- a/README.ko.md +++ b/README.ko.md @@ -154,8 +154,13 @@ sequenceDiagram │ ├── agent-sessions.db # SQLite WAL 세션 데이터베이스 │ ├── agent-sessions.yaml # 텍스트 형식의 세션 레지스트리 스냅샷 │ └── jobs/ # 비동기 잡 메타데이터 JSON 파일들 -├── scripts/ -│ └── generate-env.sh # 환경 파일(.env) 템플릿 복사 스크립트 +├── deploy/ # 배포 및 설치 도구 패키지 폴더 +│ ├── INSTALL.md # 설치 가이드 및 퀵스타트 매뉴얼 +│ ├── install_mam.sh # 로컬/클론 인스톨러 스크립트 +│ ├── generate-env.sh # 환경 파일(.env) 템플릿 복사 스크립트 +│ ├── install.sh # 원격/네트워크 인스톨러 스크립트 +│ ├── update.sh # 업데이트 헬퍼 스크립트 +│ └── remove.sh # 삭제/언인스톨 헬퍼 스크립트 ├── BOOTSTRAP.ko.md # 프로젝트 초기 설치 가이드 (한국어 백업) ├── BOOTSTRAP.md # 프로젝트 초기 설치 및 검증 상세 가이드 ├── MESSAGING.md # MQTT 메시징 프로토콜 와이어 규격서 @@ -170,7 +175,7 @@ sequenceDiagram 1. **환경 설정 파일(.env) 생성:** ```bash - ./scripts/generate-env.sh + ./deploy/generate-env.sh ``` 2. **가상환경 생성 및 의존성 패키지 설치:** ```bash diff --git a/README.md b/README.md index 267d149..b6d41fe 100644 --- a/README.md +++ b/README.md @@ -172,8 +172,13 @@ To ensure communication integrity across public MQTT brokers, the backplane inte │ ├── agent-sessions.db # SQLite WAL session database │ ├── agent-sessions.yaml # Human-readable session registry │ └── jobs/ # Asynchronous job metadata files -├── scripts/ -│ └── generate-env.sh # Environment bootstrap helper +├── deploy/ # Distribution and installation package +│ ├── INSTALL.md # User manual for installation and quick-start +│ ├── install_mam.sh # Local/Clone installer script +│ ├── generate-env.sh # Environment bootstrap helper +│ ├── install.sh # Remote/Network installer script +│ ├── update.sh # Updater script +│ └── remove.sh # Uninstaller script ├── BOOTSTRAP.md # Detailed installation and verification guide ├── MESSAGING.md # MQTT wire protocol specification └── README.md # Project introduction and overview (this file) @@ -187,7 +192,7 @@ For detailed setup instructions, please consult the **[BOOTSTRAP.md](./BOOTSTRAP 1. **Initialize Environment Config:** ```bash - ./scripts/generate-env.sh + ./deploy/generate-env.sh ``` 2. **Create Virtual Environment and Install Dependencies:** ```bash diff --git a/.agents/INSTALL.md b/deploy/INSTALL.md similarity index 88% rename from .agents/INSTALL.md rename to deploy/INSTALL.md index 217c0de..43a0916 100644 --- a/.agents/INSTALL.md +++ b/deploy/INSTALL.md @@ -11,14 +11,14 @@ MAM 스킬 및 스크립트들은 호스트 시스템의 다음 도구들에 의 * **tmux**: 에이전트를 백그라운드 격리 Pane에서 구동하기 위한 프로세스 컨테이너 * **python3**: 세션 레지스트리(YAML/SQLite DB) 파싱 및 유효성 검사 (내장 `sqlite3` 모듈 필수) * **uuidgen**: 격리 세션 생성 시 고유의 UUID 할당 -* **rsync**: 인스톨러(`install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요) +* **rsync**: 인스톨러(`deploy/install_mam.sh`)가 `.agents/` 오케스트레이터 및 스킬 폴더를 타겟 프로젝트에 복제하는 데 사용 (설치 시 필요) * **python3-yaml (pyyaml)**: 세션 데이터 YAML 저장 및 로드 의존성 (`pip install pyyaml`) --- ## 2. 🚀 자동 설치 방법 -MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `tmux`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다. +MAM의 자동 설치 스크립트(`deploy/install_mam.sh`)를 사용하여 10초 만에 필요한 규칙과 라이프사이클 툴킷을 타겟 프로젝트에 이식할 수 있습니다. 스크립트는 실행 시 자동으로 시스템의 `tmux`, `python3`, `rsync`, `uuidgen` 및 필수 파이썬 모듈들을 진단합니다. > [!IMPORTANT] > **설치 전제조건**: MAM 스킬을 타겟 프로젝트에 설치하려면 **먼저 MAM 레포지토리가 로컬 머신에 clone 되어 있어야 합니다.** @@ -27,14 +27,14 @@ MAM의 자동 설치 스크립트(`install_mam.sh`)를 사용하여 10초 만에 MAM 레포지토리 루트 디렉토리로 이동한 후 다음 명령어를 실행합니다. ```bash # 기본 사용법 (타겟 프로젝트 경로 지정) -$ bash scripts/install_mam.sh --target /path/to/your/project +$ bash deploy/install_mam.sh --target /path/to/your/project # 만약 이미 타겟에 AGENTS.md 가 존재하여 강제로 덮어쓰고 싶다면: -$ bash scripts/install_mam.sh --target /path/to/your/project --force +$ bash deploy/install_mam.sh --target /path/to/your/project --force ``` ### 설치 스크립트가 수행하는 작업: -1. **의존성 진단**: 시스템에 `tmux`, `python3`, `sqlite3` 가 설치되어 있는지 확인합니다. +1. **의존성 진단**: 시스템에 `tmux`, `python3`, `rsync`, `uuidgen` CLI 바이너리와 파이썬 `pyyaml`/`sqlite3` 모듈이 설치되어 있는지 확인합니다. 2. **규칙 및 스킬 복제**: 오케스트레이션 가이드(`.agents/` 하위 전체)를 타겟 프로젝트 하위로 이식합니다. 3. **지침 전파**: 에이전트가 로드하고 복종할 행동 지침 문서(`AGENTS.md`)를 프로젝트 루트에 복사합니다. 4. **형상 제외 설정**: 세션 DB 및 격리 캐시 저장소인 `.mam/` 디렉토리를 타겟 프로젝트의 `.gitignore` 에 자동 주입하여 불필요한 형상 관리를 방지합니다. diff --git a/deploy/README.md b/deploy/README.md index 31d747c..4b1c2a6 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -6,7 +6,10 @@ This directory contains packaging templates and installation scripts to deploy t ## 📁 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`). +* **`install.sh`**: A self-contained, idempotent remote shell installer (via curl) that checks system requirements (`tmux`, `python3`), detects NFS/network filesystem mounts, sets up a local python virtual environment (`.venv`), and initializes environment configuration (`.env`). +* **`install_mam.sh`**: A local-clone installer that copies rules/skills (`.agents/`), `AGENTS.md`, and sets up environment bootstrap on target projects. +* **`generate-env.sh`**: Environment configuration bootstrap helper. +* **`INSTALL.md`**: Detailed installation and quick-start user manual. * **`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). @@ -26,7 +29,17 @@ Alternatively, if they have cloned the repository, they can execute: bash deploy/install.sh ``` -### 2. Custom Fork / Private Mirror Installations +### 2. Local-Clone Installation +If you already have cloned this repository locally, you can port MAM to other local target projects: +```bash +bash deploy/install_mam.sh --target /path/to/your/project +``` +Refer to **`INSTALL.md`** inside this directory for the full instructions and workflows. + +> [!NOTE] +> The local-clone installer does not ship `update.sh`/`remove.sh` to targets. To enable in-place updates, re-run the remote installer (`curl ... | bash`) or copy `deploy/update.sh` + `deploy/remove.sh` manually. + +### 3. Custom Fork / Private Mirror Installations If you run a private mirror or fork, you can override the source URLs during installation using environment variables: ```bash @@ -40,7 +53,7 @@ curl -fsSL https://my-mirror.example.com/.../install.sh \ MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh ``` -### 2. Registering as a Workspace Plugin +### 4. 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`: diff --git a/scripts/generate-env.sh b/deploy/generate-env.sh similarity index 95% rename from scripts/generate-env.sh rename to deploy/generate-env.sh index af3221c..027d89a 100755 --- a/scripts/generate-env.sh +++ b/deploy/generate-env.sh @@ -6,10 +6,10 @@ # - .env present → no-op (leaves your edits intact), exit 0. # - .env present --force → overwrite .env from .env.example (backs up to .env.bak). # -# Paths are resolved relative to this script (repo root = parent of scripts/), +# Paths are resolved relative to this script (repo root = parent of deploy/), # so it works regardless of the caller's cwd. # -# Usage: scripts/generate-env.sh [--force] [-h|--help] +# Usage: deploy/generate-env.sh [--force] [-h|--help] set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" diff --git a/deploy/gitea-ci.yml b/deploy/gitea-ci.yml index 394dd82..a78d2e1 100644 --- a/deploy/gitea-ci.yml +++ b/deploy/gitea-ci.yml @@ -33,6 +33,10 @@ jobs: 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 + shellcheck deploy/install_mam.sh + shellcheck deploy/generate-env.sh + shellcheck deploy/update.sh + shellcheck deploy/remove.sh echo "✅ ShellCheck completed successfully." lint-python: diff --git a/deploy/install.sh b/deploy/install.sh index 294f14b..2bba143 100644 --- a/deploy/install.sh +++ b/deploy/install.sh @@ -152,6 +152,15 @@ if ! check_assets_present "."; then echo ".env.example" >> "$MANIFEST_FILE" fi + # Ship the user manual into the target's .agents/ (consistent with install_mam.sh) + if [ -f "$STAGE_DIR/deploy/INSTALL.md" ]; then + mkdir -p .agents + if [ ! -e ".agents/INSTALL.md" ]; then + cp "$STAGE_DIR/deploy/INSTALL.md" .agents/INSTALL.md || { echo "❌ Error: Failed to copy INSTALL.md" >&2; exit 1; } + echo ".agents/INSTALL.md" >> "$MANIFEST_FILE" + fi + fi + rm -rf "$STAGE_DIR" trap - EXIT echo "✅ Skills staged into workspace (existing files preserved)." diff --git a/scripts/install_mam.sh b/deploy/install_mam.sh similarity index 94% rename from scripts/install_mam.sh rename to deploy/install_mam.sh index 72aafa9..133fb76 100755 --- a/scripts/install_mam.sh +++ b/deploy/install_mam.sh @@ -119,11 +119,16 @@ if [ -f "$SRC_DIR/.env.example" ]; then cp "$SRC_DIR/.env.example" "$TARGET_DIR/.env.example" log_ok "Copied .env.example configuration template" fi -if [ -f "$SRC_DIR/scripts/generate-env.sh" ]; then +if [ -f "$SRC_DIR/deploy/generate-env.sh" ]; then mkdir -p "$TARGET_DIR/scripts" - cp "$SRC_DIR/scripts/generate-env.sh" "$TARGET_DIR/scripts/generate-env.sh" + cp "$SRC_DIR/deploy/generate-env.sh" "$TARGET_DIR/scripts/generate-env.sh" chmod +x "$TARGET_DIR/scripts/generate-env.sh" - log_ok "Copied scripts/generate-env.sh helper tool" + log_ok "Copied deploy/generate-env.sh helper tool" +fi +# Copy the user manual into the target's .agents/ (previously came via rsync of .agents/) +if [ -f "$SRC_DIR/deploy/INSTALL.md" ]; then + cp "$SRC_DIR/deploy/INSTALL.md" "$TARGET_DIR/.agents/INSTALL.md" + log_ok "Copied INSTALL.md user manual into target .agents/" fi # 3. Copy AGENTS.md to root or inject guidelines pointer