tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a7aa8a00fdb79f73a98d78ba0907658cb58af26e
multi-agent-mux/implementation_plan.md
T

7.6 KiB
Raw Blame History

Implementation Plan — 배포 스크립트 URL 파라미터화 (Rev.1)

  • 작성자: Planner Agent
  • 날짜: 2026-07-09
  • 상태: Draft (사용자 승인 대기)
  • 관련 리뷰 피드백: Reviewer A 이식성(portability) 스캔 결과

1. 배경 및 문제 정의

Reviewer A의 코드베이스 스캔 결과, 배포 스크립트에 배포 원본(origin) URL 3개가 하드코딩되어 있어 포크/미러/사설 Gitea 인스턴스 환경으로의 이식성이 저해됨이 확인되었습니다.

# 위치 변수 현재 하드코딩 값
1 deploy/install.sh:57 REPO_URL https://git.godopu.com/tmpl/multi-agent-mux.git
2 deploy/install.sh:58 ARCHIVE_URL https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz
3 deploy/update.sh:138 INSTALLER_URL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh

그 외 스크립트(lib.sh, create_session.sh 등)는 상대 경로 및 TARGET_DIR 파라미터화가 올바르게 적용되어 있어 이번 변경 범위에서 제외합니다.

2. 목표 (Goals)

  1. 위 3개 URL을 환경변수 MAM_REPO_URL, MAM_ARCHIVE_URL, MAM_INSTALLER_URL로 오버라이드 가능하게 파라미터화하되, 미설정 시 현재 값을 그대로 기본값으로 유지한다 (기존 사용자에 대한 동작 변경 0).
  2. 세 변수를 .env.example과 deploy/README.md에 문서화한다.
  3. 검증 절차를 명문화하여 Developer가 DoD 자가 검증에 사용할 수 있게 한다.

Non-Goals (이번 범위 제외)

  • README.md/BOOTSTRAP*.md 본문의 원라이너 예시 URL 자체를 변수화하는 것 (문서상의 예시는 실제 기본 배포 원본이므로 그대로 둔다).
  • deploy 스크립트가 .env 파일을 직접 파싱/소싱하도록 만드는 것 (§3.4 설계 결정 참조).
  • URL 간 파생 로직 (예: MAM_REPO_URL로부터 archive URL 자동 조립) — §3.5 참조.

3. 설계 (Design)

3.1. deploy/install.sh 수정

57–58행을 bash 기본값 확장 패턴으로 교체:

REPO_URL="${MAM_REPO_URL:-https://git.godopu.com/tmpl/multi-agent-mux.git}"
ARCHIVE_URL="${MAM_ARCHIVE_URL:-https://git.godopu.com/tmpl/multi-agent-mux/archive/main.tar.gz}"

3.2. deploy/update.sh 수정

138행을 동일 패턴으로 교체:

INSTALLER_URL="${MAM_INSTALLER_URL:-https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh}"

체이닝 전파 주의: update.sh는 140–142행에서 curl ... | bash -s --로 새 installer를 실행한다. 호출자가 MAM_REPO_URL=x bash update.sh 형태(명령 접두 대입)로 실행하면 해당 변수는 프로세스 환경에 export되어 자식 bash에 자동 상속되므로 별도 재-export 코드는 불필요하다. 단, 이 상속 동작이 계약임을 스크립트 주석 및 문서에 명시한다.

3.3. .env.example 문서화

새 섹션 # deploy / distribution source를 추가하고 기존 파일의 서식 규약 (#default: 라인 + 주석 처리된 변수 예시)을 따른다. 핵심 주의 문구를 반드시 포함:

이 변수들은 deploy 스크립트가 프로세스 환경에서 읽는다. install.sh는 워크스페이스에 .env가 생기기 전(curl 원라이너) 실행될 수 있고 deploy 스크립트는 .env를 파싱하지 않으므로, export MAM_REPO_URL=... 또는 명령 접두 대입으로 전달해야 한다.

3.4. 설계 결정: .env 소싱을 하지 않는 이유

  • install.sh는 설치 대상 디렉터리에 파일이 존재하기 전에 실행되므로 .env 의존이 불가능.
  • .env를 source하면 임의 셸 코드 실행 경로가 생겨 보안·부작용 리스크 발생.
  • 따라서 세 변수 모두 환경변수 단일 경로로 통일하고, .env.example에는 "문서화 + 사용법 안내" 목적으로만 등재한다.

3.5. 설계 결정: 변수 간 파생 없음

MAM_REPO_URL에서 archive/raw URL을 자동 조립하지 않는다. Gitea(/archive/main.tar.gz, /raw/branch/main/)와 GitHub(/archive/refs/heads/main.tar.gz, raw.githubusercontent.com)의 URL 스킴이 상이하여 파생 로직이 오히려 이식성을 해친다. 세 변수는 독립이며, 미러 운영 시 셋을 함께 설정하도록 문서에 권고 문구를 넣는다.

3.6. deploy/README.md 문서화

"How to Install and Deploy" 섹션에 미러/포크 설치 예시를 추가:

# Installing from a fork/mirror
curl -fsSL https://my-mirror.example.com/.../install.sh \
  | MAM_REPO_URL=https://my-mirror.example.com/me/multi-agent-mux.git \
    MAM_ARCHIVE_URL=https://my-mirror.example.com/me/multi-agent-mux/archive/main.tar.gz \
    bash

# Updating against a mirror
MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh

(파이프 실행 시 접두 대입은 bash 쪽에 붙여야 함을 예시로 보여준다.)

4. 파급 범위 및 리스크 분석

리스크 평가 완화책
기본값 오타로 기존 설치 경로 파손 중 검증 §5-3에서 기본값 문자열이 변경 전과 byte-identical한지 diff/grep으로 확인
ShellCheck 경고 (SC2154 등) 낮음 ${VAR:-default} 패턴은 미정의 변수 경고 없음. CI(gitea-ci.yml)의 shellcheck 단계로 확인
update.sh 체이닝 시 오버라이드 미전파 중 §3.2 상속 계약 주석 명시 + 검증 §5-5
문서-코드 정합성 (변수명 불일치) 낮음 task.md DoD에 변수명 3종 교차 대조 항목 포함

5. 검증 절차 (Verification Steps)

Developer는 커밋 전 아래를 순서대로 수행하고 결과를 리뷰 요청에 첨부한다.

  1. 문법 검사: bash -n deploy/install.sh deploy/update.sh — 종료코드 0.
  2. 린트: shellcheck deploy/install.sh deploy/update.sh — 신규 경고 0 (CI와 동일 조건).
  3. 기본값 무결성: grep -n 'MAM_\(REPO\|ARCHIVE\|INSTALLER\)_URL' deploy/*.sh 출력에서 :- 뒤 기본값 3개가 변경 전 하드코딩 문자열과 정확히 일치하는지 확인.
  4. 오버라이드 동작 (install.sh): 빈 스크래치 디렉터리에서 MAM_ARCHIVE_URL=https://127.0.0.1:1/nope.tar.gz bash deploy/install.sh <scratch-dir> 실행 → fetch 단계가 오버라이드된 URL로 시도하다 실패하는지 확인 (bash -x 트레이스에서 ARCHIVE_URL 해석값 확인). 실제 워크스페이스에서 실행 금지.
  5. 오버라이드 동작 (update.sh): update.sh는 기존 설치를 파괴적으로 제거하므로 전체 실행 대신 bash -x 트레이스를 138행 부근에서 조기 중단(Ctrl-C 또는 read 삽입 없이 확인 후 --force 미사용)하거나, 디스포저블 스크래치 설치본에서만 end-to-end 수행. 최소 기준: MAM_INSTALLER_URL 접두 대입 시 INSTALLER_URL 해석값이 오버라이드와 일치.
  6. 회귀 (기본 경로): 리포지토리 루트에서 bash deploy/install.sh 재실행 → check_assets_present가 충족되어 네트워크 fetch 없이 기존과 동일하게 완료되는지 확인.
  7. 문서 정합: .env.example·deploy/README.md에 세 변수명이 스크립트와 철자까지 일치하게 등재되었는지 교차 확인.

6. 산출물 및 커밋 규약

  • 변경 파일: deploy/install.sh, deploy/update.sh, .env.example, deploy/README.md
  • 단일 원자적 커밋, 메시지 제안: feat(deploy): parameterize distribution URLs via MAM_*_URL env vars
  • 완료 후 Reviewer A(논리 정합) / Reviewer B(구현 세부) 이중 리뷰 → 양측 PASS 시 마감.
Reference in New Issue View Git Blame Copy Permalink