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

Also puts the framework root on `sys.path` so every script can import the
`kb_framework` package from a plain checkout without installing it.
"""

import argparse
import os
import sys
from pathlib import Path


FRAMEWORK_ROOT = Path(__file__).resolve().parents[1]
if str(FRAMEWORK_ROOT) not in sys.path:
    sys.path.insert(0, str(FRAMEWORK_ROOT))


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