"""配置初始化：从 .env.example 复制到用户 .env，并合并缺失键。

行为对齐模板：``main.py`` 与 ``cli.app.main()`` 启动时均会调用一次。
"""
from __future__ import annotations

import os

from jiangchang_skill_core import config

from util.constants import SKILL_SLUG, SKILL_VERSION
from util.runtime_paths import get_skill_root


def bootstrap_skill_config() -> str:
    """确保用户 .env 存在，并追加 .env.example 中的新配置项。"""
    example_path = os.path.join(get_skill_root(), ".env.example")
    if not os.path.isfile(example_path):
        # demo 没有强制 .env.example，直接返回空路径
        return ""
    env_path = config.ensure_env_file(SKILL_SLUG, example_path)
    comment = f"{SKILL_SLUG} v{SKILL_VERSION}" if SKILL_VERSION else None
    config.merge_missing_env_keys(example_path, env_path, comment_skill=comment)
    return env_path