Metadata-Version: 2.4
Name: pkgmgr-kunrunic
Version: 0.1.2.dev4
Summary: Package management workflow scaffold.
Author: pkgmgr maintainers
License: MIT License
        
        Copyright (c) 2025 Jho Sung Jun
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/kunrunic/pkgmgnt
Project-URL: Repository, https://github.com/kunrunic/pkgmgnt
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: openpyxl<3.2,>=3.0; python_version < "3.8"
Requires-Dist: openpyxl>=3.1; python_version >= "3.8"
Requires-Dist: python-docx<1.0,>=0.8.11; python_version < "3.8"
Requires-Dist: python-docx>=1.1; python_version >= "3.8"
Requires-Dist: rich<13,>=10; python_version < "3.7"
Requires-Dist: rich>=13.7; python_version >= "3.7"
Dynamic: license-file

# pkgmgr

패키지 관리/배포 워크플로를 위한 Python 패키지입니다. 현재는 패키지 단위 관리와 릴리스 번들링에 초점을 둔 초기 버전입니다.

## 디자인/Use case
- 흐름 요약과 Mermaid 시퀀스 다이어그램은 [`design/mermaid/use-cases.md`](design/mermaid/use-cases.md)에 있습니다.
- 주 명령별 설정/동작 요약과 make-config/install/create-pkg/update-pkg/close-pkg 시퀀스를 포함합니다.

## 구성
- `pkgmgr/cli.py` : CLI 엔트리 (아래 명령어 참조)
- `pkgmgr/config.py` : `pkgmgr.yaml` / `pkg.yaml` 템플릿 생성 및 로더 (PyYAML 필요)
- `pkgmgr/snapshot.py`, `pkgmgr/release.py`, `pkgmgr/watch.py` : 스냅샷/패키지 수명주기/감시/릴리스 번들
- `pkgmgr/collectors/` : 컬렉터 인터페이스 및 체크섬 컬렉터 스텁
- 템플릿: `pkgmgr/templates/pkgmgr.yaml.sample`, `pkgmgr/templates/pkg.yaml.sample`

## 필요 사항
- Python 3.6 이상
- 의존성(PyYAML 등)은 `pip install pkgmgr-kunrunic` 시 자동 설치됩니다.

## 설치 (PyPI/로컬)
- PyPI(권장): `python -m pip install pkgmgr-kunrunic` (또는 `pipx install pkgmgr-kunrunic`으로 전역 CLI 설치).
- 로컬/개발: 리포지토리 클론 후 `python -m pip install .` 또는 빌드 산출물(`dist/pkgmgr_kunrunic-<버전>-py3-none-any.whl`)을 `python -m pip install dist/<파일>`로 설치.
- 확인: `pkgmgr --version` 혹은 `python -m pkgmgr.cli --version`.

## 기본 사용 흐름
아래 명령은 `pkgmgr ...` 또는 `python -m pkgmgr.cli ...` 형태로 실행합니다.  
설정 파일 기본 위치는 `~/pkgmgr/pkgmgr.yaml`이며, `~/pkgmgr/pkgmgr*.yaml`과 `~/pkgmgr/config/pkgmgr*.yaml`을 자동 탐색합니다(여러 개면 선택 필요, `--config`로 강제 지정 가능). 상태/릴리스 데이터는 `~/pkgmgr/local/state` 아래에 기록됩니다.

### 1) make-config — 메인 설정 템플릿 생성
```
pkgmgr make-config
pkgmgr make-config -o ~/pkgmgr/config/pkgmgr-alt.yaml  # 위치 지정 가능
```
편집할 주요 필드: `pkg_release_root`, `sources`, `source.exclude`, `artifacts.targets/exclude`, `git.repo_root/repo_url/keyword_prefix`, `collectors.enabled`, `actions`.

### 2) install — PATH/alias 등록 + 초기 baseline(한 번만)
```
pkgmgr install [--config <path>]
```
- 사용 쉘을 감지해 rc 파일에 PATH/alias 추가.
- `~/pkgmgr/local/state/baseline.json`이 없을 때만 초기 스냅샷 생성(있으면 건너뜀).

### 2-1) snapshot — 현재 상태 스냅샷(기준선 변경 없음)
```
pkgmgr snapshot [--config <path>]
```
- `~/pkgmgr/local/state/snapshot.json`을 새로 생성합니다.
- baseline(`baseline.json`)은 변경하지 않습니다.

### 3) create-pkg — 패키지 디렉터리/설정 생성
```
pkgmgr create-pkg <pkg-id> [--config <path>]
```
- `<pkg_release_root>/<pkg-id>/pkg.yaml`을 실제 값으로 채워 생성(기존 파일이 있으면 덮어쓰기 여부 확인).
- 메인 설정의 `git.repo_root`, `collectors.enabled`를 기본값으로 반영(`git.keywords`는 `pkg.yaml`에서 직접 입력).
- baseline이 없는 경우에만 baseline 생성.

### 4) update-pkg — Git/체크섬 수집 + 릴리스 번들 생성
```
pkgmgr update-pkg <pkg-id> [--config <path>]
```
- 최신 릴리스 종료/아카이브: `pkgmgr update-pkg <pkg-id> --release` (tar 생성 후 `HISTORY/`로 이동).
- Git: `git.repo_root`(상대/절대)에서 `git.keywords` 매칭 커밋을 모아 `message/author/subject/files/keywords` 저장.
- 체크섬: 키워드에 걸린 파일 + `include.releases` 경로의 파일 해시 수집.
- 릴리스 번들: `include.releases` 최상위 디렉터리별로 `release/<root>/release.vX.Y.Z/`를 생성. `--release` 전까지는 최신 버전을 유지하며 변경분만 추가/덮어쓰기/삭제 반영(버전 증가 없음), 이전 버전과 해시가 동일한 파일은 스킵. 각 릴리스 폴더에 `PKG_NOTE`(1회 생성, 사용자 내용 유지)와 `PKG_LIST`(매번 갱신) 작성.
- 실행 결과는 `~/pkgmgr/local/state/pkg/<id>/updates/update-<ts>.json`에 기록(`git`, `checksums`, `release` 메타 포함).

### 5) actions — 외부 작업 실행
```
pkgmgr actions
pkgmgr --config <path> actions <name> [args...]
```
- 설정의 `actions`에 등록된 작업 목록을 출력하거나, 지정한 작업을 실행합니다.
- `<name>` 뒤의 모든 인자는 액션 커맨드에 그대로 전달됩니다.
- 예: `pkgmgr --config ~/pkgmgr/pkgmgr.yaml actions export_cksum --root R --time 4`
- 예: `pkgmgr --config ~/pkgmgr/pkgmgr.yaml actions export_cksum --pkg-dir /path/to/pkg --excel /path/to/template.xlsx`

### 6) detect — baseline 대비 변경 탐지
```
pkgmgr detect [--config <path>]
```
- `pkgmgr.yaml`의 `sources/artifacts`를 매번 재스캔해 `baseline.json`과 직접 비교(`added/modified/deleted`)합니다.
- Git 변경은 보조 진단으로만 사용하며, 1차 판정 입력은 baseline 비교 결과입니다.
- `snapshot.json`은 detect의 1차 비교 입력으로 사용하지 않습니다.
- `detection.system`을 지정하면 detect 리포트/알림에 시스템명이 포함됩니다.
- `detection.report_file` 경로에 detect 텍스트 리포트를 저장합니다. 내용이 바뀐 경우 기존 파일을 `*.bak_YYYYMMDD_HHMMSS`로 자동 백업합니다.
- `pkgmgr.yaml` 관리 범위의 변경을 탐지하고, 파일별로 pkg 관리 대상 여부를 먼저 판정합니다.
- 관리 대상이면 open pkg 반영 상태(`CHANGED_NOT_UPDATED`, `DELETED_NOT_UPDATED`, `TRACKED_CHANGED_NOT_IN_PKG`, `UNTRACKED_NOT_IN_PKG`, `AMBIGUOUS_PKG`)를 점검합니다.
- 관리 비대상이면 `CHANGED_BUT_UNUSED_CHECK_REQUIRED`로 분류해 사용자 확인 대상으로 표시합니다.
- 출력은 `managed_view` + `unmanaged_view` + `git_view`(`GIT_UNTRACKED`)로 구분됩니다.
- `detection.fail_on`은 managed/unmanaged 상태코드에만 적용됩니다.
- git 차이는 `warn_count`에만 반영되고 `fail`에는 영향이 없습니다.

### 7) watch — 주기 감시 + detect + Telegram 알림(확장 채널)
```
pkgmgr watch [--config <path>] [--once] [--pkg <id>]
```
- `watch.interval_sec` 주기로 snapshot diff를 확인합니다.
- `watch.detect=true`이면 매 tick에서 detection을 함께 수행합니다.
- `watch.on_change`에 action을 지정하면 변화 감지 시 자동 실행합니다.
- `watch.telegram.enabled=true`이면 감시/탐지 요약과 확장 이벤트를 Telegram으로 전송합니다.
  - 필수: `watch.telegram.bot_token`
  - TLS: `watch.telegram.tls_verify`(기본 true), `watch.telegram.ca_file`(사설 CA 번들 경로)
  - 수신자 저장소: `watch.telegram.subscribers_file` (기본: `~/pkgmgr/config/telegram-subscribers.yaml`)
  - 하위호환: `watch.telegram.chat_id/chat_ids`는 fallback(read-only) 수신자 설정으로만 사용
  - 관리자: `watch.telegram.admin_chat_ids`에 `/approve`, `/reject` 권한 chat id 지정
  - `watch.telegram.notify_on`: detect 채널 기본 규칙(`fail|warn|changes|all`)
  - `watch.telegram.dedup=true`이면 동일 메시지 반복 전송을 방지합니다.
  - `watch.telegram.channels.*`로 채널별 활성화/옵션을 설정합니다.
    - `detect`: 기존 watch tick 결과 알림
      - `watch.telegram.channels.detect.message_file` 지정 시, detect 결과 파일에서 `summary`, `*by_reason` 섹션만 발췌 전송
      - `watch.telegram.channels.detect.max_chars` 길이 제한 초과분은 자동 생략
      - `watch.telegram.channels.detect.wrap_width`로 텔레그램 가로폭 줄바꿈 폭 조정
      - `watch.telegram.channels.detect.message_file_max_lines`로 발췌 라인 수 제한
      - 기본 요약 메시지는 `run_at + system + exit/fail/warn + by_reason` 중심으로 전송
    - `lifecycle`: `create_pkg/update_pkg/close_pkg/delete_pkg` 등 lifecycle 이벤트 알림
    - `git`: 신규 커밋(HEAD 변경) 감지 알림
    - `jenkins`: lastBuild 상태 변화(시작/성공/실패 등) 알림
    - `file_watch`: 지정 파일 내용 변경 시 본문 알림(내용 hash 기반 중복 방지)

### 8) telegram — 가입 승인 폴링/관리
```
pkgmgr telegram poll [--once] [--config <path>]
pkgmgr telegram list [--config <path>]
pkgmgr telegram approve <chat_id> [--config <path>]
pkgmgr telegram reject <chat_id> [--config <path>]
```
- `/start` 수신 시 pending 등록 후 관리자에게 승인 요청 알림 전송.
- 관리자(`/approve <chat_id>`, `/reject <chat_id>`, `/pending`) 처리 결과는 `subscribers_file`에만 반영.
- `pkgmgr.yaml`은 자동 수정하지 않습니다(오염 방지).

## auto_actions 가이드
- `auto_actions`는 pkg 라이프사이클 이벤트 이후 자동으로 실행할 `actions` 이름 목록입니다.
- 지원 이벤트:
  - `create_pkg`
  - `update_pkg`
  - `update_pkg_release`
  - `cancel_pkg_release`
  - `delete_pkg`
  - `close_pkg`
- 실행 규칙:
  - 각 이벤트의 배열 순서대로 실행됩니다.
  - 각 action은 `actions.<name>`에 정의된 command 리스트를 순서대로 실행합니다.
  - action 실행 시 `PKGMGR_CONFIG` 환경변수(현재 config 경로)가 자동 주입됩니다.
- 권장 운영 패턴:
  - `update_pkg_release`에서 `auto_cksum -> auto_pkgstore` 순으로 배치
  - `close_pkg`/`delete_pkg`에서도 `auto_pkgstore`를 연결해 상태 반영 동기화
- 예시:
```yaml
actions:
  auto_cksum:
    - cmd: python3 export_cksum.py --pkg-id {pkg_id} --excel cksum_{pkg_id}_{YYYYMMDD}_{version}
      cwd: /app/pkgmgr/plugin
      env:
        PATH: "/usr/local/python3.6/bin:/usr/local/bin:/usr/bin:/bin"
  auto_pkgstore:
    - cmd: python3 export_pkgstore.py --system TEST --push xxx@xxx.xx.x.xx --remote-dest data/pkgstore --pkg-id {pkg_id}
      cwd: /app/pkgmgr/plugin
      env:
        PATH: "/usr/local/python3.6/bin:/usr/local/bin:/usr/bin:/bin"

auto_actions:
  create_pkg: [auto_pkgstore]
  update_pkg: [auto_pkgstore]
  update_pkg_release: [auto_cksum, auto_pkgstore]
  cancel_pkg_release: [auto_pkgstore]
  delete_pkg: [auto_pkgstore]
  close_pkg: [auto_pkgstore]
```

## PATH/alias 자동 추가
- PyPI/로컬 설치 후 `python -m pkgmgr.cli install`을 실행하면 현재 파이썬의 `bin` 경로(예: venv/bin, ~/.local/bin 등)를 감지해 사용 중인 쉘의 rc 파일에 PATH/alias를 추가합니다.
- 지원 쉘: bash(`~/.bashrc`), zsh(`~/.zshrc`), csh/tcsh(`~/.cshrc`/`~/.tcshrc`), fish(`~/.config/fish/config.fish`).
- 추가 내용:
  - PATH: `export PATH="<script_dir>:$PATH"` 또는 쉘별 동등 구문
  - alias: `alias pkg="pkgmgr"` (csh/fish 문법 사용)
- 이미 추가된 경우(marker로 확인) 중복 삽입하지 않습니다. rc 파일이 없으면 새로 만듭니다.

## 템플릿 개요
- `pkgmgr/templates/pkgmgr.yaml.sample` : 메인 설정 샘플  
  - `pkg_release_root`: 패키지 릴리스 루트  
  - `sources`: 관리할 소스 경로 목록  
  - `source.exclude`: 소스 스캔 제외 패턴 (glob 지원)  
  - `artifacts.targets` / `artifacts.exclude`: 배포 대상 포함/제외 규칙 (glob 지원: `tmp/**`, `*.bak`, `**/*.tmp` 등)  
  - `watch.interval_sec`: 감시 폴링 주기
  - `watch.on_change`: 변경 시 실행할 action 이름 리스트
  - `watch.detect`: watch tick에서 detection 실행 여부
  - `watch.telegram.*`: Telegram 알림 설정(`enabled`, `bot_token`, `subscribers_file`, `admin_chat_ids`, `registration`, `message_prefix`, `notify_on`, `dedup`, `channels`, `chat_id/chat_ids(fallback)`)
  - `collectors.enabled`: 기본 활성 컬렉터(현재 collect 명령은 stub 기반)
  - `detection.enabled/ignore/fail_on/warn_on`: detection 동작/정책 제어
  - `detection.system`: detect 보고/알림에 포함할 시스템 식별자
  - `actions`: action 이름 → 실행할 커맨드 목록 (각 항목에 `cmd` 필수, `cwd`/`env` 선택)

- `pkgmgr/templates/pkg.yaml.sample` : 패키지별 설정 샘플  
  - `pkg.id` / `pkg.root` / `pkg.status(open|closed)`  
  - `include.releases`: 릴리스에 포함할 경로(최상위 디렉터리별로 묶여 `release/<root>/release.vX.Y.Z` 생성)  
  - `git.repo_root/keywords/since/until`: 커밋 수집 범위  
  - `collectors.enabled`: 패키지별 컬렉터 설정

## 주의
- `snapshot`은 기준선을 바꾸지 않는 독립 상태 캡처입니다(`snapshot.json`).
- `install`과 `create-pkg`는 동일한 `baseline.json`을 사용하며, baseline이 없을 때만 생성됩니다.
- `detect`는 현재 정책 기반 분류/출력은 제공하지만, collector 고도화 및 watch 연동은 확장 단계입니다.

## 확장성 가이드
- `actions`를 기본 확장 포인트로 사용합니다. 배포/내보내기/알림 등은 액션으로 위임하는 것을 권장합니다.
- 릴리스 번들 포맷(`release/<root>/release.vX.Y.Z/`, `PKG_LIST`, `PKG_NOTE`)은 외부 도구와의 연동 기준점으로 사용합니다.
- `~/pkgmgr/local/state/pkg/<id>/updates/update-<ts>.json`은 자동화 파이프라인에서 읽을 수 있는 결과물로 취급합니다.
- 전역 수집/집계는 `collectors` 확장으로 흡수할 계획입니다.

## TODO (우선순위)
- detection 출력 포맷 고도화: managed/unmanaged 분류 기준 튜닝, 정책 필터 옵션 추가.
- 컬렉터 파이프라인 구현: 체크섬 외 collector 등록/선택/실행 로직 정식 연결.
- watch 연동 고도화: detection 결과 기반 트리거/알림 흐름 정리.
- 테스트/CI 확장: detection/watching/lifecycle 통합 테스트 보강.
