agent-confhub-cli 0.1.0__tar.gz

agent_confhub_cli-0.1.0/.claude/rules/architecture.md

@@ -0,0 +1,6 @@
+# 아키텍처 원칙
+
+- **Registry 의존성 주입**: 모든 코어 클래스는 `Registry(base_path)` 또는 `base_path`를 주입받는다. 하드코딩된 `~/.nexus` 경로 사용 금지.
+- **resolved/ 불변성**: `root/`와 `apps/` 원본은 절대 수정하지 않는다. 병합 결과는 반드시 `resolved/`에만 쓴다.
+- **심볼릭 링크 단위**: 에이전트 폴더(`.claude/` 등) 전체를 단위로 링크한다. 개별 파일 링크 금지.
+- **links.json이 링크 레지스트리**: 심볼릭 링크 상태는 `links/links.json`에서 추적한다. 파일시스템 탐색만으로 상태를 판단하지 않는다.

agent_confhub_cli-0.1.0/.claude/rules/coding.md

@@ -0,0 +1,27 @@
+# 코딩 규칙
+
+## 타입 안전성
+
+- `str | None` 파라미터를 `str`을 받는 함수에 전달하기 전에 반드시 `assert param is not None`으로 타입을 좁힌다.
+- `Optional[X]` 대신 `X | None` 문법을 사용한다 (Python 3.10+).
+
+## 파일 입출력
+
+- 모든 파일 열기에 `encoding="utf-8"`을 명시한다.
+- 설정 파일 포맷: Registry 메타 → YAML, 링크 정보 → JSON, 에이전트 설정 → YAML.
+
+## CLI 패턴
+
+- 오류 발생 시 `print_error()`로 메시지를 출력하고 `raise typer.Exit(1)`로 종료한다.
+- Registry 미초기화 상태는 `RegistryNotFoundError`로 처리하고 `nxs init` 실행을 안내한다.
+- 성공/경고/오류는 `print_success()` / `print_warning()` / `print_error()` 헬퍼로 구분 출력한다.
+
+## 린트/타입 검사
+
+```bash
+uv tool run ruff check . --fix   # import 정렬, 미사용 import 등 자동 수정
+uv tool run ruff format .        # 포맷 적용
+uv tool run ty check nexus/      # 타입 오류 확인
+```
+
+커밋 전 위 세 명령이 오류 없이 통과해야 한다.

agent_confhub_cli-0.1.0/.claude/rules/testing.md

@@ -0,0 +1,6 @@
+# 테스트 규칙
+
+- 모든 테스트는 `tmp_path` fixture를 사용해 임시 디렉토리에서 실행한다. 실제 `~/.nexus` 경로를 건드리지 않는다.
+- `Registry.DEFAULT_PATH`와 `Registry.NEXUSRC_PATH`는 `monkeypatch`로 패치한다.
+- 새 기능 추가 시 대응하는 단위 테스트를 `tests/`에 추가한다.
+- 테스트 실행: `uv run pytest` (전체), `uv run pytest tests/<file>.py` (개별)

agent_confhub_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(.venv/bin/pytest tests/ -v)",
+      "Bash(uv tool:*)",
+      "WebSearch"
+    ]
+  }
+}

agent_confhub_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Install ty
+        run: uv pip install ty --system
+
+      - name: Run ruff (lint + format check)
+        run: |
+          ruff check .
+          ruff format --check .
+
+      - name: Run ty (type check)
+        run: ty check nexus/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Run tests
+        run: pytest tests/ -v --cov=nexus --cov-report=term-missing
+
+      - name: Upload coverage report
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'

agent_confhub_cli-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+*.egg
+
+# Nexus
+resolved/
+
+# Editor
+.DS_Store
+.idea/
+.vscode/
+
+# env
+.env*

agent_confhub_cli-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  # ruff: fast Python linter & formatter
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.10
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # pytest: run tests before commit
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: pytest tests/ --tb=short -q
+        language: system
+        pass_filenames: false
+        always_run: true

agent_confhub_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,97 @@
+# Nexus CLI
+
+AI 에이전트(Claude, Gemini, Codex, Cursor, Copilot) 설정을 중앙에서 관리하고 프로젝트별 심볼릭 링크로 적용하는 CLI 프레임워크. CLI 명령어: `nxs`.
+
+## 개발 환경 설정
+
+```bash
+# 의존성 설치
+uv sync
+uv sync --extra dev   # 개발 의존성 포함
+
+# 테스트 실행
+uv run pytest
+uv run pytest tests/test_registry.py  # 특정 파일
+uv run pytest -v --cov=nexus           # 커버리지 포함
+
+# CLI 실행
+uv run nxs --help
+
+# 린트/타입 검사
+uv tool run ruff check .
+uv tool run ty check nexus/
+```
+
+## 핵심 개념
+
+| 개념 | 설명 |
+|------|------|
+| **Registry** | `~/.nexus` - 설정의 중앙 저장소. `Registry(base_path)`로 주입 |
+| **Root Config** | `root/agents/<agent>/` - 모든 앱이 상속하는 기본 설정 |
+| **App** | `apps/<app>/` - 프로젝트 단위 설정 묶음. Root를 상속·오버라이드 |
+| **Resolved** | `resolved/<app>/<agent>/` - root + app 병합 결과 (자동 생성) |
+| **Link** | 프로젝트의 `.claude/` 등을 `resolved/` 경로로 심볼릭 링크 |
+
+## Registry 디렉토리 구조
+
+```
+~/.nexus/
+├── nexus.config.yaml
+├── root/agents/
+│   └── claude/
+│       ├── agent.config.yaml
+│       └── .claude/
+│           ├── CLAUDE.md
+│           └── settings.json
+├── apps/
+│   └── web-frontend/
+│       ├── app.config.yaml
+│       └── agents/
+│           └── claude/
+│               ├── agent.config.yaml
+│               └── .claude/
+│                   ├── CLAUDE.md
+│                   └── settings.json
+├── resolved/          # nxs resolve로 자동 생성, 레포에 커밋 대상
+│   └── web-frontend/
+│       └── claude/
+│           └── .claude/
+└── links/
+    └── links.json
+```
+
+## 지원 에이전트
+
+| ID | 에이전트 | 링크 대상 |
+|----|----------|-----------|
+| `claude` | Anthropic Claude | `.claude/` |
+| `gemini` | Google Gemini | `.gemini/` |
+| `codex` | OpenAI Codex | `AGENTS.md` |
+| `cursor` | Cursor AI | `.cursorrules` |
+| `copilot` | GitHub Copilot | `.github/copilot-instructions.md` |
+
+## CLI 명령어
+
+```bash
+nxs init [--path PATH] [--from-repo URL]
+nxs app add <name> / list / show <name> / remove <name>
+nxs agent add <agent> --app <app>|--root
+nxs agent show/list/remove <agent> --app <app>|--root
+nxs resolve <app> / --all / --dry-run
+nxs link <app> [--target PATH] [--agent claude,gemini]
+nxs unlink <app>
+nxs submodule add <app> [--target PATH] [--agent claude,gemini]
+nxs submodule remove <app> [--target PATH] [--agent claude,gemini] [--keep-submodule]
+nxs sync push [--message MSG] / pull / remote set <url>
+nxs status [--app NAME] [--with-links]
+nxs install [--from-repo URL] [--verify] [--apps app1,app2]
+```
+
+## 병합 전략
+
+| 전략 | 동작 | 기본 대상 |
+|------|------|-----------|
+| `append` | 루트 내용 + 구분선 + 앱 내용 | `.md` 파일 |
+| `deep-merge` | JSON 필드 단위 재귀 병합, 스칼라는 앱이 오버라이드 | `.json` 파일 |
+| `replace` | 앱 내용이 루트를 완전 대체 | 명시적 지정 시 |
+| `prepend` | 앱 내용 앞에 루트 내용 추가 | 명시적 지정 시 |

agent_confhub_cli-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: agent-confhub-cli
+Version: 0.1.0
+Summary: AI 에이전트 설정 중앙 관리 CLI 프레임워크
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'

agent_confhub_cli-0.1.0/README.md

@@ -0,0 +1,195 @@
+# Nexus CLI (`nxs`)
+
+AI 에이전트(Claude, Gemini, Codex, Cursor, Copilot) 설정을 팀 전체에 중앙 관리하는 CLI 프레임워크.
+
+## 개념 구조
+
+```mermaid
+graph TD
+    R["~/.nexus (Registry)"]
+    ROOT["root/agents/claude/\n팀 공통 기본 설정"]
+    APP["apps/api-server/agents/claude/\n프로젝트별 설정"]
+    RESOLVED["resolved/api-server/claude/\n병합 결과 (자동 생성)"]
+    REMOTE["nexus-config\n(private git repo)"]
+    PROJECT["api-server 프로젝트\n.nexus-config/ (submodule)"]
+    SYMLINK[".claude/ 심볼릭 링크"]
+
+    ROOT -->|"상속 + 오버라이드"| RESOLVED
+    APP -->|"nxs resolve"| RESOLVED
+    RESOLVED -->|"nxs sync push"| REMOTE
+    REMOTE -->|"git submodule"| PROJECT
+    PROJECT -->|"nxs submodule init"| SYMLINK
+```
+
+## 설치
+
+```bash
+pipx install agent-confhub-cli
+```
+
+## 빠른 시작
+
+```bash
+# Registry 초기화
+nxs init
+
+# 앱 등록
+nxs app add web-frontend
+
+# Claude 에이전트 설정 추가
+nxs agent add claude --app web-frontend
+
+# 설정 병합
+nxs resolve web-frontend
+
+# 프로젝트에 심볼릭 링크 연결
+nxs link web-frontend --target /workspace/my-project
+```
+
+## 주요 명령어
+
+| 명령어 | 설명 |
+|--------|------|
+| `nxs init` | Registry 초기화 |
+| `nxs app add/list/show/remove` | 앱 관리 |
+| `nxs agent add/list/show/remove` | 에이전트 설정 관리 |
+| `nxs resolve <app>` | 설정 병합 빌드 |
+| `nxs link <app>` | 프로젝트에 심볼릭 링크 |
+| `nxs unlink <app>` | 링크 해제 |
+| `nxs submodule add <app>` | 프로젝트에 git submodule + sparse-checkout으로 설정 적용 |
+| `nxs submodule init <app>` | 클론 후 sparse-checkout 및 심볼릭 링크 설정 (팀원용) |
+| `nxs submodule remove <app>` | submodule 설정 제거 |
+| `nxs sync push/pull` | Git 동기화 |
+| `nxs status` | Registry 상태 확인 |
+| `nxs install --from-repo <url>` | 회사 레포 설치 |
+
+## 지원 에이전트
+
+| 에이전트 | 링크 대상 |
+|----------|----------|
+| `claude` | `.claude/` |
+| `gemini` | `.gemini/` |
+| `codex` | `AGENTS.md` |
+| `cursor` | `.cursorrules` |
+| `copilot` | `.github/copilot-instructions.md` |
+
+## 팀 공유 워크플로우
+
+### 심볼릭 링크 방식 (개인 머신 로컬 적용)
+
+```mermaid
+sequenceDiagram
+    participant A as 설정 관리자
+    participant R as ~/.nexus (Registry)
+    participant G as nexus-config (git)
+    participant T as 팀원
+
+    A->>R: nxs app add / nxs agent add
+    A->>R: 파일 직접 편집
+    A->>R: nxs resolve <app>
+    A->>G: nxs sync push
+    T->>G: nxs sync pull
+    T->>R: nxs resolve --all
+    Note over T: 심볼릭 링크로<br/>연결된 프로젝트에 즉시 반영
+```
+
+```bash
+# 설정 관리자 - 설정 변경 후 push
+nxs sync push --message "feat: Claude 설정 업데이트"
+
+# 팀원 - pull 후 resolve로 로컬 반영
+nxs sync pull && nxs resolve --all
+```
+
+### Git Submodule 방식 (sparse-checkout으로 앱 설정만 적용)
+
+nexus-config 레포 전체가 아닌 해당 앱의 `resolved/<app>/` 만 체크아웃합니다.
+
+```mermaid
+sequenceDiagram
+    participant A as 설정 관리자
+    participant N as ~/.nexus (Registry)
+    participant G as nexus-config (git)
+    participant P as api-server 프로젝트
+    participant T as 팀원
+
+    A->>N: nxs app add api-server
+    A->>N: nxs agent add claude --app api-server
+    A->>N: 파일 직접 편집
+    A->>G: nxs submodule add api-server --target ./api-server
+    Note over A,G: resolve → push → submodule add<br/>→ sparse-checkout 자동 수행
+    A->>P: .nexus-config/ submodule + .claude/ 심볼릭 링크 생성
+    A->>P: git push (프로젝트 레포)
+
+    T->>P: git clone api-server
+    T->>P: nxs submodule init api-server
+    Note over T,P: sparse-checkout + 심볼릭 링크 자동 설정
+```
+
+**설정 관리자 (최초 1회):**
+
+```bash
+# 1. Registry를 private 레포와 연결
+nxs sync remote set https://github.com/your-team/nexus-config.git
+
+# 2. 앱 및 에이전트 설정 준비
+nxs app add api-server
+nxs agent add claude --app api-server
+# ~/.nexus/apps/api-server/agents/claude/ 에서 직접 파일 편집
+
+# 3. 프로젝트에 submodule 적용
+#    resolve → remote push → git submodule add → sparse-checkout 자동 수행
+nxs submodule add api-server --target /workspace/api-server
+```
+
+**프로젝트 레포에 생성되는 구조:**
+
+```
+api-server/
+├── .nexus-config/    ← nexus-config submodule (resolved/api-server/ 만 sparse-checkout)
+├── .claude/          ← symlink → .nexus-config/resolved/api-server/claude/.claude/
+├── .gemini/          ← symlink → .nexus-config/resolved/api-server/gemini/.gemini/
+└── ...
+```
+
+개발자는 `.claude/`, `.gemini/` 등 프로젝트 루트의 심볼릭 링크만 사용하면 됩니다. `.nexus-config/` 내부 구조는 신경 쓸 필요 없습니다.
+
+**팀원 (레포 클론 후):**
+
+```bash
+# 심볼릭 링크는 레포에 이미 커밋되어 있어 별도 생성 불필요
+git clone --recurse-submodules https://github.com/your-team/api-server.git
+cd api-server
+
+# sparse-checkout 적용 (resolved/api-server/ 만 체크아웃)
+nxs submodule init api-server
+```
+
+**설정 업데이트:**
+
+```mermaid
+flowchart LR
+    E["파일 직접 편집\n~/.nexus/apps/api-server/..."]
+    S["nxs submodule add api-server\n--target ./api-server"]
+    GP["git push\n(프로젝트 레포)"]
+    T["팀원: git pull\n+ git submodule update\n+ nxs submodule init api-server"]
+
+    E --> S --> GP --> T
+```
+
+```bash
+# ~/.nexus/apps/api-server/agents/claude/ 파일 직접 수정 후
+nxs submodule add api-server --target /workspace/api-server
+# resolve → nexus push → submodule ref + 심볼릭 링크 커밋
+
+# 팀원은 프로젝트에서 반영
+git pull && git submodule update
+nxs submodule init api-server  # sparse-checkout 재적용
+```
+
+## 개발
+
+```bash
+uv sync --extra dev
+pytest tests/ -v
+```

agent_confhub_cli-0.1.0/nexus/__init__.py

@@ -0,0 +1,3 @@
+"""Nexus CLI - AI 에이전트 설정 중앙 관리 프레임워크"""
+
+__version__ = "0.1.0"

agent_confhub_cli-0.1.0/nexus/cli.py

@@ -0,0 +1,113 @@
+"""Nexus CLI - 진입점 모듈"""
+
+from pathlib import Path
+
+import typer
+
+from nexus import __version__
+from nexus.commands import agent as agent_cmd
+from nexus.commands import app as app_cmd
+from nexus.commands.link import link_app
+from nexus.commands.submodule import submodule_app
+from nexus.commands.sync import sync_app
+
+app = typer.Typer(
+    name="nxs",
+    help="Nexus CLI - AI 에이전트 설정 관리",
+    add_completion=False,
+)
+
+app.add_typer(app_cmd.app, name="app")
+app.add_typer(agent_cmd.app, name="agent")
+app.add_typer(link_app, name="link")
+app.add_typer(submodule_app, name="submodule")
+app.add_typer(sync_app, name="sync")
+
+
+def version_callback(value: bool):
+    """버전 정보 출력 콜백"""
+    if value:
+        typer.echo(f"nexus-cli version: {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="현재 버전을 출력합니다.",
+        callback=version_callback,
+        is_eager=True,
+    ),
+):
+    """Nexus CLI - AI 에이전트 설정 중앙 관리 프레임워크"""
+
+
+@app.command("init")
+def init_command(
+    path: Path | None = typer.Option(None, "--path", "-p", help="Registry 경로"),
+    from_repo: str | None = typer.Option(None, "--from-repo", help="Git 레포 URL에서 초기화"),
+):
+    """Nexus Registry를 초기화합니다."""
+    from nexus.commands.init import do_init
+
+    do_init(path, from_repo)
+
+
+@app.command("resolve")
+def resolve_command(
+    app_name: str | None = typer.Argument(None, help="앱 이름 (생략시 --all 필요)"),
+    all_apps: bool = typer.Option(False, "--all", "-a", help="모든 앱 빌드"),
+    dry_run: bool = typer.Option(False, "--dry-run", help="결과 미리보기 (파일 미생성)"),
+):
+    """설정을 병합하여 resolved 디렉토리에 저장합니다."""
+    from nexus.commands.resolve import do_resolve
+
+    do_resolve(app_name, all_apps, dry_run)
+
+
+@app.command("unlink")
+def unlink_command(
+    app_name: str = typer.Argument(..., help="앱 이름"),
+    target: Path | None = typer.Option(
+        None, "--target", "-t", help="링크 해제할 프로젝트 경로 (기본: 현재 디렉토리)"
+    ),
+    agent: str | None = typer.Option(
+        None, "--agent", help="특정 에이전트만 해제 (쉼표 구분: claude,gemini)"
+    ),
+):
+    """프로젝트의 심볼릭 링크를 해제합니다."""
+    from nexus.commands.link import do_unlink
+
+    do_unlink(app_name, target, agent)
+
+
+@app.command("status")
+def status_command(
+    app_name: str | None = typer.Option(None, "--app", help="특정 앱 이름"),
+    with_links: bool = typer.Option(False, "--with-links", help="링크 상태 포함"),
+):
+    """Registry 상태를 표시합니다."""
+    from nexus.commands.status import do_status
+
+    do_status(app_name, with_links)
+
+
+@app.command("install")
+def install_command(
+    from_repo: str | None = typer.Option(None, "--from-repo", help="Git 레포 URL에서 설치"),
+    verify: bool = typer.Option(False, "--verify", help="설치 상태 확인"),
+    apps: str | None = typer.Option(
+        None, "--apps", help="특정 앱만 설치 (쉼표 구분: web-frontend,api-server)"
+    ),
+):
+    """Git 레포에서 Registry를 설치합니다."""
+    from nexus.commands.install import do_install
+
+    do_install(from_repo, verify, apps)
+
+
+if __name__ == "__main__":
+    app()