Installer Architecture

이 문서는 기여자가 빠른 설치 안내에서 설치기 호환성 계약으로 넘어갈 때 사용하는 구조 안내입니다. 설치기, 훅 입력·출력, 설치 상태와 테스트 사이의 연결을 설명합니다.

사용자는 설치 안내에서 실행 절차를 확인하실 수 있습니다. 기여자는 플랫폼 호환성 계약에서 요구 조건과 담당 테스트를 확인합니다.

Contents

• 읽는 순서
• Architecture Summary
• Install Flow
• Install Record
• Gateway Lifecycle
• Platform Surfaces
• State And Safety Model
• Contributor Entry Points
• What Not To Infer
• Full Understanding

읽는 순서

1. 이 문서에서 구성 요소와 호출 방향을 파악합니다.
2. 파일 위치는 repository structure에서 찾습니다.
3. 사용자에게 보이는 동작은 installation과 uninstall에서 확인합니다.
4. 계약과 필요한 검증은 installer platform compatibility, tool output semantics, live smoke regression에서 확인합니다.

Architecture Summary

설치기 구성 요소는 다음 세 계층에서 역할을 나눕니다.

설치기는 설치 파일과 훅을 갱신하면서 사용자가 수정한 파일을 보호하고 자신의 변경을 기록합니다. status, doctor, 업데이트와 제거 절차는 이 기록을 읽어 실제 설치 상태와 복원 가능한 변경을 판단합니다.

설치된 훅 런타임은 같은 런타임 루트 아래에 _shared 모듈과 session-intent-analyzer/scripts/session_intent_ledger.py를 함께 포함합니다. 네이티브 훅과 Ghost-ALICE Autopilot은 이 설치본에서 원장 API와 관련 모듈을 불러옵니다. 소스 체크아웃은 설치 입력을 지정하며, 소스 편집만으로 설치된 훅의 실행 모듈이 바뀌지 않습니다. 원장 데이터베이스 경로와 네이티브 세션 식별자는 별도의 실행 입력입니다.

공용 모듈 네 개는 어느 계층에도 속하지 않으므로 설치기, 훅 런타임과 스킬이 모두 가져올 수 있습니다. _shared/hook_definitions.py는 설치기와 훅 런타임이 함께 읽는 이름을 소유합니다. 훅 ID와 호스트 이벤트 이름, ghost_alice_context 제공자 이름, 권한 어댑터 허용 목록이 여기에 있습니다. _shared/install_lock.py는 설치 잠금 파일과, 잠금을 이 프로세스나 이 프로세스를 실행한 부모 프로세스가 쥐었는지 판정하는 함수 하나를 소유합니다. _shared/content_digest.py는 설치 내용의 지문 생성과 설치 기록 항목·현재 파일의 비교를 소유합니다. _shared/installed_payload.py는 설치 기록을 소유합니다. 앞의 세 모듈은 표준 라이브러리만 가져오고, installed_payload는 content_digest와 install_lock만 가져옵니다. 런타임 모듈은 설치기 모듈을 가져오지 않고, 설치기 모듈은 런타임 모듈을 가져오지 않습니다. _shared.test_hook_definitions가 이 규칙들을 검사하고, installer 패키지의 모듈 이름이 표준 라이브러리 모듈 이름과 겹치지 않는지도 검사합니다.

Install Flow

Windows에서는 install.cmd가 인수를 install.ps1에 전달합니다. install.ps1과 install.sh는 같은 _shared/installer/cli.py를 실행하는 얇은 셸이므로, Windows와 Unix 계열은 설치기 구현 하나를 함께 씁니다. Unix 계열 환경에서는 install.sh가 셸 진입점을 담당하며 필요할 때 Bash로 다시 실행합니다. --help와 --list를 포함한 모든 명령은 Python에서 실행됩니다. 셸은 설치기 문구, 옵션, 명령의 사본을 갖지 않습니다.

installer.cli는 명령 표 COMMAND_LINE 하나를 소유합니다. 명령 행마다 그 명령을 고르는 토큰, 처리 함수, 쥐는 설치 잠금 이름, 플랫폼이 필요한지, --help 행이 있습니다. 옵션 해석, 자동 모드 판정, 명령 분기, 잠금, --help가 모두 이 표를 읽으므로, 한 곳에만 알려진 명령은 생기지 않습니다. -로 시작하면서 명령 이름이 아닌 토큰은 Unknown option으로 멈춥니다. 감지한 플랫폼마다 실행되는 것은 플랫폼 없이 받은 설치뿐이고, 명령은 한 번만 실행됩니다. 설치기는 자신이 실행되는 체크아웃을 installer.runner.REPO_ROOT 한 이름으로 부릅니다.

설치 단계 순서

설치 명령은 다음 순서로 진행합니다. installer.cli.prepare_install이 1단계를 실행하고, installer.cli.run_command가 잠금을 잡은 뒤, installer.cli.run_install이 나머지를 실행합니다. _shared/test_installer_cli.py가 이 순서를 고정합니다.

1. 선행 도구(git, node)와 소스 체크아웃의 git hook 경로.
2. 설치 잠금(~/.ghost-alice/install.lock). 명령이 끝날 때까지 쥡니다. 설치기는 잠금을 생성한 직후, 저널이 done도 restored도 아닌 게시를 모두 복원합니다.
3. 설치 기록 이관. ~/.ghost-alice/installed-payload.json이 없고 이전 설치기의 install-state가 있을 때만 실행합니다. 그다음 소스 상태 확인, 그다음 대상 수집(핵심 스킬, _shared, 애드온 대상).
4. deprecated 설치 스킬을 발견 경로 밖으로 옮긴 뒤, 인코딩 검사, 그다음 로컬 수정을 격리하거나 기록하는 사전 점검.
5. 중단된 애드온 제거를 재개합니다. 애드온 충돌은 설치를 멈춥니다.
6. 배치: _shared와 모든 대상을 링크(Claude Code)로, 또는 하나의 복사 배치(Codex)로 놓습니다. 배치 한 번은 install_transaction.py publish 한 번이며, 같은 단계에서 대상들의 설치 기록 항목을 작성합니다.
7. 런타임 _shared 게시. 등록된 컨텍스트 게이트웨이의 모듈이 바뀌었으면 게시 조정이 서비스를 중지하고 다시 게시한 뒤 재시작합니다. 조정은 런타임 폴더, ~/.codex, ~/.claude, 원장, 서비스 파일을 게이트웨이 의존으로 보고, 영수증이 함께 기록한 Codex 복사본 ~/.agents/skills/_shared는 의존으로 보지 않습니다. 그래서 Codex 복사 배치는 그 복사본을 조정 없이 교체하고, 게이트웨이 모듈이 바뀐 경우 그다음 런타임 게시가 멈춥니다. 그다음 읽기만 하는 Context gateway: 보고 줄 하나, 그다음 훅 설치, 관리 규칙 블록, 명령 래퍼.
8. 검증, 소유 표지, merge-companion 스냅숏, 애드온 사이드카, 설치 상태 매니페스트, 설치 이벤트. 설치기는 배치 뒤에 이 이전 기록들을 예전처럼 작성하며, status·doctor·보존·제거·복구는 이 기록들을 계속 조회합니다.

명령 표가 명령마다 잠금을 지정합니다. 설치, 제거, 복구(--repair), --cleanup-pending, gateway 전달 명령이 잠금 아래에서 실행되며, installer.cli.run_command가 처리 함수 전에 잠금을 잡고 끝난 뒤 풉니다. 자식 도구는 자신을 호출한 설치기 프로세스의 잠금을 그대로 씁니다. 잠금 파일이 그 프로세스 ID를 기록하며, install_lock.held_by_process_tree가 잠금이 호출한 프로세스나 그 부모 프로세스의 것인지 판정합니다. 게이트웨이 조정과 설치 기록 작성 함수가 모두 이 함수를 호출하며, 무관한 소유자는 둘을 막습니다. 잠금의 소유자 문자열은 표시용이며 아무 권한도 주지 않습니다.

Install Record

~/.ghost-alice/installed-payload.json은 설치기가 어느 위치에 무엇을 설치했는지 기록합니다. 두 호스트가 파일 하나를 함께 쓰며, 설치 위치 경로마다 항목이 하나입니다. 런타임 ~/.ghost-alice/runtime/current/_shared처럼 두 호스트가 함께 쓰는 위치는 항목 하나의 used_by에 두 호스트를 기록합니다.

복사 항목의 files는 상대 경로마다 파일 내용의 sha256:<hex> 지문을 기록하며, 파일 하나를 복사한 항목은 자기 자신을 경로 .로 기록합니다. 링크 항목은 링크가 가리키는 경로만 기록합니다. content_digest가 둘을 생성하며 캐시(__pycache__, .pytest_cache, .mypy_cache, .ruff_cache, node_modules, .git), .pyc·.DS_Store 파일, 소유 표지 파일, 링크인 파일과 폴더를 제외합니다. baseline은 지문의 출처입니다. recorded는 게시가 작성한 지문, migrated는 이전 설치기의 기록에서 이관한 지문, unknown은 이전 기록에 지문이 없었다는 뜻입니다.

installed_payload.update는 기록 섹션을 작성하는 유일한 함수이고, installed_payload.restore는 게시가 보관한 사본으로 기록을 복원합니다. 두 함수는 임시 파일에 작성한 뒤 이름을 변경하여 교체하며, 설치 잠금이 호출한 프로세스나 그 부모 프로세스의 것이 아니면 거부합니다. 다른 schema version처럼 이 설치기가 읽을 수 없는 기록은 변경하지 않고, 파일 게시는 계속합니다. --status와 --doctor는 기록에서 해당 플랫폼의 대상을 요약한 줄 하나와, 기록과 다른 대상마다 줄 하나를 출력합니다. 기준값이 없는 대상은 개수만 알리고 비교하지 않으며, 일치는 비교한 대상에 대해서만 보고합니다. 기록은 두 명령의 결과를 변경하지 않습니다.

flowchart TB
    REQ["installer.transaction이 게시 요청 하나를 작성"]
    JR["publish가 rollbacks/txid/journal.json(prepare)과 기록 사본을 작성"]
    ST["사본 준비: 설치 위치 옆에 복사본 또는 링크를 생성하고, 저널에 원래 상태와 준비한 결과를 기록"]
    PUB["게시: 원래 파일을 rollbacks/txid/로 이동하고, 준비한 결과의 이름을 설치 위치로 변경하고, 기록을 갱신"]
    DONE["저널에 done을 기록하고, 완료된 폴더는 최근 20개를 유지"]
    RS["복원: 원래 파일과 보관한 기록을 복원하고, 저널에 restored를 기록하고, 원인의 종료 코드를 유지"]
    NEXT["다음 잠금 명령: recover --txid가 prepare인 저널을 복원"]
    REQ --> JR --> ST --> PUB --> DONE
    ST -->|"실패"| RS
    PUB -->|"실패, 게이트웨이 조정 포함"| RS
    JR -.->|"프로세스 중지"| NEXT

게시는 교체한 자료를 ~/.ghost-alice/rollbacks/<txid>/ 한 곳에만 보관합니다. 원래 파일, 기록 사본, journal.json이 그 폴더에 있습니다. 저널은 게시가 교체하는 대상을 기록하고, 대상마다 원래 상태와 준비한 결과를 기록합니다. 파일은 지문, 링크는 가리키는 경로, 폴더는 빈 폴더까지 모두 기록하며 캐시와 생성 파일만 제외합니다. 저널은 무엇이든 변경하기 전에 prepare, 파일·기록·게이트웨이 조정이 모두 끝난 뒤 done, 복원한 뒤 restored를 기록합니다. 게이트웨이 오류는 복원 뒤에도 자신의 종료 코드(2, 3, 4, 5)를 유지합니다. 프로세스가 done 전에 중지되면 다음 잠금 명령이 install_transaction.py recover --txid <id>를 호출합니다. 이 명령은 모든 대상을 먼저 확인합니다. 설치 위치에는 게시가 남긴 결과나 원래 파일이 있어야 하고, 이동한 원래 파일이 남아 있어야 합니다. 복원할 수 없는 게시는 명령을 종료 코드 1로 중지하고 검토할 폴더를 알립니다. 절반만 게시된 파일 위에 다시 게시하면 어느 파일이 원래 파일인지 판별할 수 없기 때문입니다. 이 복원은 파일과 기록만 복원하며 컨텍스트 게이트웨이 서비스를 중지하거나 재시작하지 않습니다.

Gateway Lifecycle

게이트웨이 설치·갱신·해제는 _shared/context_gateway_*의 여섯 모듈이 담당합니다. model은 요청·관측값·계획·결과와 실행 인터페이스의 자료형을 정의하며 AI 모델을 호출하지 않습니다. inventory는 전달받은 플랫폼 어댑터로 사실을 읽습니다. plan은 소유권을 확인하고 변경 대상과 실제 게이트웨이 의존성을 비교하여 I/O 없이 순서가 정해진 계획을 만듭니다. transaction은 계획 실행과 역순 복구를 담당합니다. platform은 개별 파일·네이티브 서비스 작업을 수행합니다. install은 기존 Python·CLI 진입점에서 이 모듈들을 연결합니다.

일반 파일 교체는 install_transaction.py의 되돌릴 수 있는 ReplacementBatch 작업을, 관리형 Git 업데이트는 installer_source_update.py의 되돌릴 수 있는 SourceUpdate 작업을 제공합니다. 선택한 경로가 소유권이 확인된 게이트웨이에 영향을 주면 같은 게이트웨이 트랜잭션이 교체 전에 서비스를 중지하고 후보 서비스의 준비 상태를 확인한 뒤 설치 명세와 등록 바인딩을 갱신합니다. 무관함이 확인된 변경은 게이트웨이를 그대로 둡니다. Core 정리는 영향을 받는 게이트웨이를 먼저 해제한 뒤 의존 파일을 삭제합니다. 소유권이나 의존성을 확인할 수 없으면 해제와 그에 의존하는 삭제를 허용하지 않습니다.

게이트웨이 설치 CLI의 --dry-run 옵션은 확인한 변경 계획을 출력하고 실제 반영이나 승인 대기 없이 종료합니다. 게이트웨이·컴포넌트 오류는 발생 단계와 고정 오류 식별자를 유지합니다. 종료 코드 2는 선행 조건 불충족, 3은 활성 파일 교체 전 서비스 상태 확인 불가, 4는 작업 실패 후 이전 설치 복원, 5는 변경 시작 후 복구 확인 불가를 뜻합니다. 일반 셸·PowerShell 호출자는 기존 전체 실패 보고와 구조화된 컴포넌트 원인을 유지합니다. 설치에는 zstd 코덱이 동작하는 Python 3.14가 필요하며 해제는 Python 3.11을 지원합니다. 설치 생명주기 명세에서 작업별 조건, 자료 전달과 실패 분기를 확인하실 수 있습니다.

Platform Surfaces

Claude Code의 native skill invocation과 hook permission은 저장소 밖의 세션에 필요한 global instruction을 대신하지 않습니다. installer는 platforms/claude/CLAUDE.md의 managed block을 Claude config directory에 병합합니다. Codex의 별도 bootstrap과 hook config는 required gate를 SKILL.md read record와 hook payload로 감사할 수 있게 합니다. 두 global rule file은 managed block 밖의 사용자 텍스트를 보존하며, marker가 없는 사용자 파일에는 덮어쓰기 대신 .ghost-alice-proposed 제안 파일을 만듭니다.

일반 Core hook 전달은 실제 native cwd를 Core 맥락으로 유지하고 명시된 Ghost-ALICE Autopilot 대상 override를 보존합니다. 프로젝트 선택은 Ghost-ALICE Autopilot이 담당합니다. Claude는 절대 CLI 프로젝트 경로를 payload cwd보다 먼저 선택하며, Codex는 payload cwd를 사용하고 Claude 전용 힌트를 무시합니다. 설치 source와 프로젝트 신뢰 경로는 Ghost-ALICE Autopilot 대상을 선택하지 않으며, 격리 바인딩은 소유 프로젝트 대상을 유지합니다. Pretool과 Stop은 해당 대상을 선택하고 OFF를 읽은 뒤 Core 권한 자료에 접근합니다. OFF는 캡처 맥락이나 권한 읽기·쓰기 없이 조용히 계속 진행을 반환하며, 활성 대상은 기존 적격 선택 검사로 진행합니다. 대상 선택은 권한을 부여하지 않습니다.

관리 훅 명령과 네이티브 신뢰 항목은 검토한 설치 내용과 일치해야 합니다. 실행 중인 호스트가 이전 등록을 유지할 수 있으므로 적절히 재로드한 뒤 실제 네이티브 콜백으로 반영을 확인합니다. 훅 신뢰와 재로드를 참고해 주세요. 설치 상태만으로 네이티브 실행을 입증하지 않습니다.

State And Safety Model

설치기는 제거·복원할 대상을 추측하지 않도록 변경 내용을 기록합니다.

설치된 파일, 훅이나 실행 설정을 바꾸는 개발자는 상태 조회, 진단, 병합 대기 처리와 제거 복원에 미치는 영향도 확인해야 합니다. 이 절차들은 같은 설치 기록에 의존합니다.

Contributor Entry Points

기여자는 구성 요소를 바꿀 때 연결된 계약을 확인합니다. 호환성 표가 지정한 담당 테스트에서 영향을 받는 회귀 검사를 찾습니다.

What Not To Infer

• 훅 파일의 존재만으로 현재 입력·출력 계약과 일치한다고 판단하지 않습니다.
• 복사된 스킬 디렉터리만으로 플랫폼이 해당 스킬을 호출하거나 감사할 수 있다고 판단하지 않습니다.
• 설치 점검의 통과만으로 상태 조회·진단·업데이트·병합 대기·제거 절차의 일관성을 판단하지 않습니다.
• 사용자용 설치 명령은 진입점을 안내하며 내부 구조 설명을 대신하지 않습니다.

Full Understanding

기여자는 검토할 변경이 셸 진입점에서 설치 조정 코드, 설치 대상, 상태 기록과 담당 테스트로 어떻게 이어지는지 확인합니다. 이 문서는 그 연결을 찾는 안내이며, 관련 구현과 호환성 계약을 읽는 절차를 대신하지 않습니다.