# 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 기본값 확장 패턴으로 교체:

```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행을 동일 패턴으로 교체:

```bash
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" 섹션에 미러/포크 설치 예시를 추가:

```bash
# 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 시 마감.