"""Resolve the selected data directory consistently for framework command-line tools."""

import argparse
import os
from pathlib import Path


FRAMEWORK_ROOT = Path(__file__).resolve().parents[1]


def parse_vault_args(parser: argparse.ArgumentParser) -> argparse.Namespace:
    """Add the shared CLI contract and return a validated absolute vault root."""
    parser.add_argument(
        "--vault-root",
        help="data directory (default: KNOWLEDGE_BASE_ROOT, then framework root)",
    )
    args = parser.parse_args()
    raw = args.vault_root if args.vault_root is not None else os.environ.get(
        "KNOWLEDGE_BASE_ROOT", str(FRAMEWORK_ROOT)
    )
    if not raw.strip():
        parser.error("vault root must not be empty")
    root = Path(raw).expanduser().resolve()
    if not root.is_dir():
        parser.error(f"vault root must be an existing directory: {root}")
    args.vault_root = root
    return args