Metadata-Version: 2.4
Name: docmesh-config
Version: 0.2.0
Summary: DocMesh environment configuration, diagnosis, and runtime-plan metadata
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic-settings>=2.14.2
Dynamic: license-file

# docmesh-config

DocMesh 애플리케이션을 위한 환경변수 설정 로딩, 실행 전 진단, runtime plan 메타데이터 라이브러리다. 외부 서비스 client 생성, 연결, 상태 확인 및 runtime 실행은 담당하지 않는다.

설정 정의, 서비스 선택, 요구사항 및 진단은 `ConfigurationManifest`에서 하나의 선언적 계약으로 관리한다. 기본 제공 설정을 상속한 애플리케이션 전용 설정은 기본 manifest를 변경하지 않고 파생 manifest에 등록할 수 있다.

## 주요 API

- `RuntimePlan`, `Service`, `HealthcheckPolicy`: 선언적 서비스 선택과 startup 정책 메타데이터
- `ConfigurationManifest`, `ConfigDefinition`, `ConfigRegistry`: 설정 정의·선택·요구사항을 묶는 manifest API
- `ConfigurationEvaluation`, `EnvironmentSnapshot`: 한 환경에 대한 typed 설정과 secret-safe 평가 결과
- `LoadedConfigurations`: manifest 평가에서 로딩된 설정에 대한 이름 기반 typed 접근
- `build_runtime_plan_metadata()`: plan과 환경 진단을 결합한 secret-safe 메타데이터 생성
- `diagnose_services()`: 설정 상태, 필수·대안 조합 및 production 보안 위험 진단
- `ConfigError`, `ConfigIssue`, `EnvironmentDiagnosis`: 구조화된 secret-safe 오류와 진단 결과

```python
from docmesh_config import RuntimePlan, Service, diagnose_services

plan = RuntimePlan(
    services=(Service.POSTGRES.required(), Service.SQLITE.optional()),
    one_of=((Service.POSTGRES, Service.SQLITE),),
)
diagnosis = diagnose_services(plan=plan)

if not diagnosis.ok:
    for issue in diagnosis.issues:
        print(issue.env_key, issue.reason, issue.remediation)
```

확장 설정은 애플리케이션 소유의 파생 manifest에 등록한다.

```python
from docmesh_config import (
    ConfigDefinition,
    ConfigurationManifest,
    KeycloakConfig,
)


class AppKeycloakConfig(KeycloakConfig):
    admin_api_url: str


manifest = (
    ConfigurationManifest.standard().extend(
        ConfigDefinition(
            name="app_keycloak",
            settings_type=AppKeycloakConfig,
            env_prefix="APP_KEYCLOAK_",
        )
    )
    .select("app_keycloak")
    .require("app_keycloak")
)
evaluation = manifest.evaluate()
config = evaluation.configs.require("app_keycloak", AppKeycloakConfig)
```

`manifest.evaluate()`는 외부 연결 없이 설정 로딩, 진단 및 요구사항 충족 여부를 한 번에 계산한다. `diagnose_services()`와 `build_runtime_plan_metadata()`는 이 manifest 코어를 사용하는 편의 함수다.

## 개발

```bash
pytest
```

제품 요구사항은 [`docs/prd.md`](docs/prd.md), 소프트웨어 요구사항은 [`docs/srs.md`](docs/srs.md)를 참고한다.
