ros-dds-manager 0.1.0__tar.gz

ros_dds_manager-0.1.0/.env.example

@@ -0,0 +1,2 @@
+ROS_DDS_MANAGER_APP__DEFAULT_VENDOR=cyclonedds
+ROS_DDS_MANAGER_LOGGING__LEVEL=INFO

ros_dds_manager-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.env

ros_dds_manager-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ros_dds_manager-0.1.0/AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+`ros-dds-manager` 프로젝트에 기여하는 AI 코딩 에이전트 및 개발자를 위한 아키텍처 및 개발 지침서입니다.
+
+---
+
+## 1. 프로젝트 아키텍처 및 디렉토리 구조
+
+```
+ros-dds-manager/
+├── src/ros_dds_manager/
+│   ├── __init__.py           # 공개 API 및 라이브러리 인터페이스 (모듈 export 정의)
+│   ├── errors.py             # 도메인 예외 클래스 및 표준 종료 코드 (clig.dev 준수)
+│   ├── main.py               # wpycli 기반 CLI 엔트리포인트 및 런타임 설정
+│   ├── models.py             # DDSProfile, DDSVendor 등 불변/데이터 클래스
+│   ├── generator.py          # Jinja2 기반 DDS XML 렌더링 및 문법 검증
+│   ├── templates/            # cyclonedds.xml.j2, fastdds.xml.j2 템플릿
+│   ├── storage.py            # 프로파일 파일 I/O, 활성 상태 및 current.sh 관리
+│   ├── network.py            # 호스트 네트워크 인터페이스/IP 감지 (Linux ip -j addr)
+│   ├── config_mgr.py         # 앱 설정(config.toml) 입출력 및 키-값 파서
+│   └── commands/             # 서브커맨드 모듈 분리
+│       ├── profile_cmd.py    # list, show, switch/use, env, generate, init, delete
+│       ├── doctor_cmd.py     # doctor (진단 리포트)
+│       ├── run_cmd.py        # run (서브프로세스 환경 주입 실행)
+│       └── config_cmd.py     # config (init, show, path, set, get)
+├── tests/                    # pytest 테스트 스위트
+│   ├── test_cli.py           # CLI 엔드투엔드 통합 테스트
+│   ├── test_config.py        # 설정 관리 단위 테스트
+│   ├── test_generator.py     # XML 템플릿 렌더링 및 파싱 테스트
+│   ├── test_models.py        # 모델 직렬화/역직렬화 및 환경변수 계산 테스트
+│   └── test_storage.py       # 파일시스템 저장소 생명주기 테스트
+├── pyproject.toml            # 프로젝트 메타데이터, 의존성, ruff 설정
+├── CHANGELOG.md              # Keep a Changelog 규격 변경 이력
+└── README.md                 # 사용자용 매뉴얼 및 시나리오 가이드
+```
+
+---
+
+## 2. 개발 및 TDD 원칙 (Test-Driven Development)
+
+1. **테스트 우선/동반 (Test-First / Co-evolution)**:
+   - 새로운 기능이나 버그 수정을 진행할 때는 반드시 `tests/` 디렉토리에 대응하는 단위 또는 통합 테스트를 추가/보완해야 합니다.
+   - 테스트 실행:
+     ```bash
+     uv run pytest
+     ```
+2. **엄격한 린트 및 코드 스타일 준수**:
+   - `ruff` 검사를 통과해야 하며, 불필요한 import나 미사용 변수가 없어야 합니다.
+   - 린트 검사 및 자동 수정:
+     ```bash
+     uv run ruff check .
+     uv run ruff check --fix .
+     ```
+3. **간결하고 명확한 주석**:
+   - 코드에 불필요한 개발자 독백이나 장황한 설명을 남기지 마세요.
+   - 복잡한 도메인 지식(예: Fast-DDS discovery locator, CycloneDDS buffer watermark)에 대해서만 명확한 인라인 주석을 작성하세요.
+
+---
+
+## 3. CLI 가이드라인 준수 원칙 ([clig.dev](https://clig.dev/))
+
+다른 에이전트가 CLI 인터페이스를 확장할 때 다음 규칙을 반드시 준수해야 합니다:
+
+### 3.1 입력 및 대화형 제어 (Input & Non-interactive safety)
+- `init` 마법사 같은 대화형 프롬프트는 반드시 `sys.stdin.isatty() and sys.stdout.isatty()` 상태 및 `--no-input` 플래그를 검사해야 합니다.
+- TTY가 아니거나 `--no-input`이 켜져 있는 환경에서는 무한 대기하지 말고 `EXIT_USAGE (2)`로 즉시 실패하며, 비대화형 대체 명령어(`generate` 등)를 안내해야 합니다.
+
+### 3.2 파괴적 작업 확인 (Destructive Safety)
+- `delete` 등의 파괴적 작업은 `--yes (-y)` 플래그를 제공해야 합니다.
+- 비대화형 환경에서 `--yes`가 누락된 채 파괴적 명령이 실행되면 `EXIT_USAGE (2)`로 안전하게 차단해야 합니다.
+
+### 3.3 출력 스트림 분리 (Output Separation)
+- **stdout**: 순수 데이터, 명령어 처리 결과, `--json` 출력, `env`의 export 구문.
+- **stderr**: 에러 메시지, 경고, 진단 안내 문구.
+- 스크립팅 자동화를 위해 주요 조회 명령어(`list`, `show`, `doctor`)에 `--json (-j)` 플래그를 지원해야 합니다.
+- `-q, --quiet` 플래그 지정 시 팁(tip)이나 부가 배너 출력을 억제합니다.
+
+### 3.4 표준 종료 코드 (Standard Exit Codes)
+`ros_dds_manager.errors`에 정의된 상수를 일관되게 반환하세요:
+- `EXIT_SUCCESS = 0`: 작업 성공
+- `EXIT_ERROR = 1`: 런타임/운영 오류 (프로파일 없음, 파일 쓰기 실패 등)
+- `EXIT_USAGE = 2`: 잘못된 인수, 비대화형 입력 누락, 확인 플래그 미지정
+- `EXIT_NOT_FOUND = 127`: `run` 명령에서 대상 실행 파일 미발견
+- `EXIT_INTERRUPT = 130`: SIGINT (Ctrl+C)
+
+---
+
+## 4. 신규 DDS 벤더 추가 절차
+
+새로운 DDS 벤더(예: RTI Connext DDS, GurumDDS)를 추가하려면:
+1. `src/ros_dds_manager/models.py`:
+   - `DDSVendor` 열거형에 새 벤더 추가
+   - `rmw_implementation` 및 `get_env_vars`에 필요한 환경변수(예: `NDDS_QOS_PROFILES`) 매핑 추가
+2. `src/ros_dds_manager/templates/`:
+   - `<vendor>.xml.j2` Jinja2 템플릿 파일 생성
+3. `src/ros_dds_manager/commands/profile_cmd.py`:
+   - `build_generate_command()`에 해당 벤더 전용 서브커맨드 및 플래그 추가
+4. `tests/`:
+   - `test_generator.py`에 XML 렌더링 테스트 추가
+   - `test_cli.py`에 CLI 생성/활성화 테스트 추가
+
+---
+
+## 5. 릴리스 및 PyPI 배포
+
+버전의 단일 소스는 `src/ros_dds_manager/__init__.py`의 `__version__`이다. `pyproject.toml`은 `dynamic = ["version"]` + `[tool.hatch.version]`로 이 값을 읽는다. **버전을 다른 곳에 중복 기재하지 마세요.**
+
+릴리스 절차:
+1. `CHANGELOG.md`의 `[Unreleased]` 항목을 새 버전 섹션으로 이동.
+2. `__version__` 갱신.
+3. `uv run ruff check . && uv run pytest` 통과 확인.
+4. `uv build && uvx twine check dist/*` 통과 확인.
+5. `v<version>` 형식의 태그를 push하면 `.github/workflows/release.yml`이 PyPI로 게시한다.
+
+배포는 PyPI Trusted Publishing(OIDC)으로만 수행하며, 저장소에 API 토큰을 두지 않는다. 워크플로는 다음 등록 정보와 정확히 일치해야 한다:
+
+| 항목 | 값 |
+| --- | --- |
+| Owner | `wkqco33` |
+| Repository | `ros-dds-manager` |
+| Workflow name | `release.yml` |
+| Environment name | `pypi` |
+
+태그 버전과 패키지 버전이 다르면 워크플로가 게시 전에 실패한다.

ros_dds_manager-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-22
+
+### Packaging & Distribution
+- PyPI 배포 메타데이터 정비: PEP 639 라이선스 표현(`Apache-2.0`), `authors`, `keywords`, `classifiers`, `[project.urls]` 추가.
+- 버전을 `src/ros_dds_manager/__init__.py` 단일 소스로 통합 (`dynamic = ["version"]` + `[tool.hatch.version]`). CLI 버전도 동일 상수를 참조.
+- sdist에서 개발용 `config.toml` 및 CI 워크플로를 제외.
+- Trusted Publishing(OIDC) 기반 `release.yml` 워크플로 추가 (태그-버전 일치 검증 → 린트/테스트 → 빌드 → PyPI 게시).
+- CI를 Python 3.12/3.13 매트릭스로 확장.
+- README에 PyPI 설치 안내 및 배지 추가.
+
+### Added
+- **Core Models & Generator**:
+  - `DDSProfile` and `DDSVendor` supporting `cyclonedds` and `fastdds`.
+  - Jinja2 template rendering for CycloneDDS (`cyclonedds.xml.j2`) and Fast-DDS (`fastdds.xml.j2`).
+  - Strict XML syntax validation using `xml.etree.ElementTree`.
+- **Profile Management**:
+  - `ros-dds-manager list`: Table and machine-readable `--json`, `--plain` output.
+  - `ros-dds-manager show [name]`: Metadata, XML preview, and environment variables inspection.
+  - `ros-dds-manager switch <name>` / `use <name>`: Profile activation and symlink management (`current.sh`, `current.xml`).
+  - `ros-dds-manager env [name]`: Outputs sourceable shell `export` statements (`--unset` supported).
+  - `ros-dds-manager delete <name>`: Deletes profile with interactive confirmation or `--yes` flag.
+  - `ros-dds-manager generate <vendor>`: CLI flags generator with `--dry-run` preview.
+  - `ros-dds-manager init [name]`: Interactive wizard with auto-detected network interfaces.
+  - `ros-dds-manager run <profile> -- <command...>`: Subprocess execution with profile environment.
+  - Short command alias `rddm` registered alongside `ros-dds-manager`.
+- **Config Management**:
+  - `ros-dds-manager config init`: Initializes global or local `config.toml`.
+  - `ros-dds-manager config show`: Displays active configuration (`--json` supported).
+  - `ros-dds-manager config path`: Resolves configuration file location.
+  - `ros-dds-manager config set <key> <value>`: Updates configuration keys.
+  - `ros-dds-manager config get <key>`: Reads specific configuration value.
+- **Diagnostics & Network Discovery**:
+  - `ros-dds-manager doctor`: Full health check (`--json` supported) for ROS distro, active profile, environment variables, and network cards.
+  - Network interface inspection utility (`network.py`) using Linux `ip -j addr`.
+- **CLI Standards (clig.dev) Compliance**:
+  - Standard exit codes (0: success, 1: error, 2: usage/input required, 127: not found, 130: interrupt).
+  - TTY and non-interactive `--no-input` safety.
+  - XDG Base Directory specification compliance (`XDG_CONFIG_HOME`).
+  - Typed domain exceptions in `errors.py`.

ros_dds_manager-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing to ros-dds-manager
+
+`ros-dds-manager` 프로젝트에 관심을 가져주셔서 감사합니다! 기여를 위한 지침은 다음과 같습니다.
+
+---
+
+## 개발 환경 설정
+
+1. **저장소 클론 및 패키지 설치**:
+   ```bash
+   uv sync --group dev
+   ```
+
+2. **테스트 실행**:
+   ```bash
+   uv run pytest
+   ```
+
+3. **린트 및 코드 스타일 검사**:
+   ```bash
+   uv run ruff check .
+   uv run ruff check --fix .
+   ```
+
+---
+
+## 기여 가이드라인
+
+- **TDD (테스트 주도 개발)**: 버그 수정이나 새 기능 추가 시 항상 `tests/` 디렉토리에 테스트 코드를 포함하세요.
+- **CLI 원칙 준수**: 대화형 입력, JSON 출력, 종료 코드 등 [clig.dev](https://clig.dev/) 원칙과 `AGENTS.md` 지침을 따르세요.
+- **Commit 메시지**: Conventional Commits (예: `feat: ...`, `fix: ...`, `docs: ...`, `test: ...`) 형식을 권장합니다.

ros_dds_manager-0.1.0/LICENSE

@@ -0,0 +1,122 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License.

ros_dds_manager-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: ros-dds-manager
+Version: 0.1.0
+Summary: ROS 2 DDS(CycloneDDS, Fast-DDS) XML 설정 생성 및 프로파일 전환 CLI
+Project-URL: Homepage, https://github.com/wkqco33/ros-dds-manager
+Project-URL: Repository, https://github.com/wkqco33/ros-dds-manager
+Project-URL: Issues, https://github.com/wkqco33/ros-dds-manager/issues
+Project-URL: Changelog, https://github.com/wkqco33/ros-dds-manager/blob/main/CHANGELOG.md
+Author-email: wkqco33 <wkqco33@users.noreply.github.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,cyclonedds,dds,fastdds,rmw,robotics,ros2
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.12
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: wpycli>=0.3.2
+Requires-Dist: wpyconf
+Requires-Dist: wpylog
+Description-Content-Type: text/markdown
+
+# ros-dds-manager (`rddm`)
+
+[![PyPI version](https://img.shields.io/pypi/v/ros-dds-manager.svg)](https://pypi.org/project/ros-dds-manager/)
+[![Python versions](https://img.shields.io/pypi/pyversions/ros-dds-manager.svg)](https://pypi.org/project/ros-dds-manager/)
+[![License](https://img.shields.io/pypi/l/ros-dds-manager.svg)](https://github.com/wkqco33/ros-dds-manager/blob/main/LICENSE)
+[![CI](https://github.com/wkqco33/ros-dds-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/wkqco33/ros-dds-manager/actions/workflows/ci.yml)
+
+ROS 2 환경에서 DDS(CycloneDDS, Fast-DDS 등)의 복잡한 XML 설정 파일을 자동으로 생성하고, 상황에 맞추어 손쉽게 전환/적용할 수 있는 CLI 도구 및 Python 라이브러리입니다.
+
+> **Tip**: 긴 명령어 대신 짧은 단축 별칭 **`rddm`**을 사용할 수 있습니다. (`ros-dds-manager`와 완전히 동일)
+> ```bash
+> rddm list
+> rddm switch sim-local
+> ```
+
+---
+
+## 📦 설치 (Installation)
+
+PyPI에서 바로 설치합니다. Python 3.12 이상이 필요합니다.
+
+```bash
+# CLI 도구로 설치 (권장)
+uv tool install ros-dds-manager
+# 또는
+pipx install ros-dds-manager
+
+# 라이브러리로 사용
+pip install ros-dds-manager
+```
+
+설치 후 `ros-dds-manager` 또는 `rddm` 명령을 사용할 수 있습니다.
+
+```bash
+ros-dds-manager --version
+rddm doctor
+```
+
+<details>
+<summary>소스에서 개발 환경 구성</summary>
+
+```bash
+git clone https://github.com/wkqco33/ros-dds-manager.git
+cd ros-dds-manager
+uv sync
+uv run rddm --help
+```
+
+</details>
+
+---
+
+## 🚀 빠른 시작 (Quick Start)
+
+### 1. 새 프로파일 생성
+```bash
+# 로컬호스트 격리 (공용 WiFi에서 토픽 충돌 방지)
+uv run ros-dds-manager generate cyclonedds sim-local --localhost --domain-id 1 --activate
+
+# 특정 유선 NIC 및 피어 지정 (Fast-DDS 멀티캐스트 비활성화)
+uv run ros-dds-manager generate fastdds robot-eth --interface eth0 --no-multicast --peers 192.168.1.10,192.168.1.11
+
+# 생성 미리보기 (Dry Run)
+uv run ros-dds-manager generate cyclonedds preview-test --localhost --dry-run
+
+# 대화형 마법사 실행 (TTY 전용)
+uv run ros-dds-manager init
+```
+
+### 3. 프로파일 목록 및 상세 조회
+```bash
+uv run ros-dds-manager list
+uv run ros-dds-manager list --json
+uv run ros-dds-manager show sim-local
+```
+
+### 4. 프로파일 전환 (Switch)
+```bash
+# 활성 프로파일 교체
+uv run ros-dds-manager switch sim-local
+# 또는 별칭 사용
+uv run ros-dds-manager use sim-local
+```
+
+### 5. 쉘 환경변수 연동 방법 (3가지 방식 지원)
+CLI 도구(자식 프로세스)는 부모 쉘의 환경변수를 직접 바꿀 수 없으므로, 편의에 맞게 세 가지 방식 중 하나를 사용할 수 있습니다:
+
+1. **`~/.bashrc` 영구 연동 (가장 추천)**:
+   ```bash
+   echo 'source ~/.config/ros-dds-manager/current.sh' >> ~/.bashrc
+   ```
+   `switch` 명령어로 활성 프로파일을 바꾸면 `current.sh`가 즉시 갱신되므로, 새 터미널마다 자동으로 선택된 DDS 환경이 적용됩니다.
+
+2. **현재 쉘 즉시 적용 (one-shot)**:
+   ```bash
+   eval "$(ros-dds-manager env)"
+   # 또는
+   source ~/.config/ros-dds-manager/current.sh
+   ```
+
+3. **명령어 격리 실행 (`run`)**:
+   현재 쉘 환경변수를 일체 건드리지 않고, 해당 프로파일이 적용된 서브프로세스로 실행합니다:
+   ```bash
+   ros-dds-manager run sim-local -- ros2 topic list
+   ```
+
+---
+
+## 📋 주요 명령어 (Commands)
+
+| 명령어 | 설명 | 예시 |
+| :--- | :--- | :--- |
+| `list` | 저장된 모든 DDS 프로파일 목록 및 활성 상태 표시 (`--json`, `--plain`) | `ros-dds-manager list --json` |
+| `show [name]` | 프로파일 상세 정보, 생성된 XML, 환경변수 출력 (`--json`) | `ros-dds-manager show sim-local` |
+| `switch <name>` | 활성 프로파일 변경 및 `current.sh` 갱신 | `ros-dds-manager switch robot-eth` |
+| `env [name]` | 쉘 `export` 구문 출력 (`--unset` 지원) | `eval "$(ros-dds-manager env)"` |
+| `generate` | 플래그 기반으로 XML 및 프로파일 생성 (`--dry-run`, `--overwrite`) | `ros-dds-manager generate cyclonedds my-prof --localhost` |
+| `init [name]` | 대화형 마법사 질문-답변으로 프로파일 생성 (TTY 전용) | `ros-dds-manager init` |
+| `delete <name>`| 프로파일 삭제 (`--yes` 지원) | `ros-dds-manager delete old-profile --yes` |
+| `run <name> -- <cmd>` | 특정 프로파일 환경을 주입하여 명령 실행 | `ros-dds-manager run sim-local -- ros2 launch ...` |
+| `doctor` | ROS 2 환경변수, 활성 XML, 네트워크 상태 진단 (`--json`) | `ros-dds-manager doctor` |
+| `config` | 앱 설정(`config.toml`) 관리 (`init`, `show`, `path`, `set`, `get`) | `ros-dds-manager config show` |
+
+---
+
+## 🛡️ CLI 표준 준수 ([clig.dev](https://clig.dev/))
+
+### 1. 표준 종료 코드 (Exit Codes)
+| 코드 | 의미 | 설명 |
+| :--- | :--- | :--- |
+| `0` | `EXIT_SUCCESS` | 명령어가 성공적으로 완료됨 |
+| `1` | `EXIT_ERROR` | 일반 런타임/운영 오류 (프로파일 없음 등) |
+| `2` | `EXIT_USAGE` | 잘못된 플래그/인수 또는 비대화형 환경에서 필수 입력/확인(`--yes`) 누락 |
+| `127`| `EXIT_NOT_FOUND` | `run` 명령에서 대상 실행 파일을 찾을 수 없음 |
+| `130`| `EXIT_INTERRUPT` | 사용자가 Ctrl+C(SIGINT)로 인터럽트함 |
+
+### 2. 표준 플래그
+- `--json` / `-j`: 기계 판독이 용이한 JSON 형태로 출력 (CI/CD 및 파이프라인 연동)
+- `--no-input`: 프롬프트 대기 없이 즉시 실패 (CI/에이전트 안전 장치)
+- `-q`, `--quiet`: 팁과 상태 배너 출력을 억제하여 순수 결과만 표기
+- `-y`, `--yes`: 파괴적 작업(`delete`) 시 확인 절차 스킵
+- `--dry-run`: 실제 디스크 저장 없이 생성될 XML과 환경변수 미리보기
+
+### 3. XDG Base Directory 규격 준수
+설정 파일 및 프로파일 저장소는 다음 우선순위에 따라 결정됩니다:
+1. `ROS_DDS_MANAGER_DIR` (사용자 지정 환경변수)
+2. `$XDG_CONFIG_HOME/ros-dds-manager` (지정된 경우)
+3. `~/.config/ros-dds-manager` (기본값)
+
+---
+
+## ⚙️ 설정 관리 (`config` 서브 커맨드)
+
+`ros-dds-manager` 자체 동작 설정(`config.toml`)을 관리합니다:
+
+- `ros-dds-manager config path`: 설정 파일 경로 및 존재 여부 확인 (`--local` 지원)
+- `ros-dds-manager config show`: 현재 적용된 설정 내용 확인 (`--json` 지원)
+- `ros-dds-manager config init`: 기본 `config.toml` 초기화 (`--overwrite`, `--local` 지원)
+- `ros-dds-manager config set <key> <value>`: 설정값 변경 (예: `ros-dds-manager config set app.default_vendor fastdds`)
+- `ros-dds-manager config get <key>`: 특정 키값 조회 (예: `ros-dds-manager config get app.default_vendor`)
+
+---
+
+## 💡 주요 시나리오별 설정 예제
+
+### 시나리오 1: 연구실/카페 공용 WiFi에서 시뮬레이션 혼선 방지 (Localhost 전용)
+```bash
+ros-dds-manager generate cyclonedds local-gazebo \
+    --localhost \
+    --domain-id 1 \
+    --activate
+```
+
+### 시나리오 2: 로봇 내부의 특정 이더넷 카드(`enp4s0`)로 통신 고정
+```bash
+ros-dds-manager generate cyclonedds robot-wired \
+    --interface enp4s0 \
+    --domain-id 42 \
+    --buffer-mb 20 \
+    --activate
+```
+
+### 시나리오 3: 멀티캐스트가 차단된 망에서 Fast-DDS 유니캐스트 피어 연결
+```bash
+ros-dds-manager generate fastdds office-unicast \
+    --no-multicast \
+    --peers 192.168.10.20,192.168.10.21 \
+    --activate
+```
+
+### 시나리오 4: Fast-DDS Discovery Server 연결 (대규모 분산 로봇)
+```bash
+ros-dds-manager generate fastdds ds-client \
+    --discovery-server client \
+    --server-ip 192.168.1.100 \
+    --server-port 11811 \
+    --activate
+```
+
+---
+
+## 🛠️ 개발 및 기여
+- 에이전트 개발 지침: [AGENTS.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/AGENTS.md)
+- 변경 이력: [CHANGELOG.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/CHANGELOG.md)
+- 기여 가이드: [CONTRIBUTING.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/CONTRIBUTING.md)
+- 보안 정책: [SECURITY.md](file:///home/wkqco/Workspace/utils/ros-dds-manager/SECURITY.md)
+- 라이선스: [LICENSE](file:///home/wkqco/Workspace/utils/ros-dds-manager/LICENSE) (Apache-2.0)