kd-cli 2.0.4__py3-none-any.whl

kd/config.py

@@ -0,0 +1,853 @@
+"""YAML-based configuration with hierarchical resolution.
+
+Flat-key resolution chain (first match wins per key):
+
+1. CLI flags
+2. Local config — ``.kd/config.yaml`` found by walking up from cwd
+3. Global config — ``~/.config/kd/config.yaml``
+4. Built-in default
+
+Command-option resolution chain (10-level, via :func:`resolve_command_defaults`):
+
+1. CLI flag (caller skips options already in ``raw_options``)
+2. Env var (N/A for command options)
+3. Project command default — ``projects.<PROJ>.defaults.<cmd>.<opt>``
+4. Local command default — ``defaults.<cmd>.<opt>`` in local config
+5. Local flat key — ``limit``/``output`` in local config
+6. Connection command default — ``connections.<name>.defaults.<cmd>.<opt>``
+7. Connection flat key — ``limit``/``output`` on the active connection
+8. Global command default — ``defaults.<cmd>.<opt>`` in global config
+9. Global flat key — ``limit``/``output`` in global config
+10. Built-in default — from ``OptionDeclaration.default``
+
+Use :func:`resolve_config` to get a :class:`ResolvedConfig` with per-key
+source tracking.  Lower-level :func:`load_config` / :func:`save_config`
+remain available for single-file operations.
+"""
+
+from __future__ import annotations
+
+import os
+from enum import StrEnum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, NamedTuple
+
+import yaml
+from pydantic import BaseModel
+
+from kd.connection import ConnectionConfig
+from kd.debug import DebugLog
+from kd.exceptions import ConfigError
+
+if TYPE_CHECKING:
+    from kd.cli.core.option_registry import OptionDeclaration
+
+DEFAULT_CONFIG_PATH = Path.home() / ".config" / "kd" / "config.yaml"
+
+# Environment variable names for config keys that support env override.
+# url/token moved to per-connection auth (token_cmd / token_env).
+_ENV_MAP: dict[str, str] = {
+    "default_connection": "KD_CONNECTION",
+}
+
+# Origin labels for flag-sourced entries (overrides "--{key}" default).
+_FLAG_ORIGINS: dict[str, str] = {
+    "default_connection": "-c",
+}
+
+
+# ---------------------------------------------------------------------------
+# Resolution types
+# ---------------------------------------------------------------------------
+
+
+class ConfigSource(StrEnum):
+    """Where a resolved config value came from."""
+
+    FLAG = "flag"
+    ENV = "env"
+    LOCAL = "local"
+    GLOBAL = "global"
+    DEFAULT = "default"
+
+
+class ResolvedValue(NamedTuple):
+    """A config value together with its provenance."""
+
+    value: str
+    source: ConfigSource
+    origin: str  # e.g. "-c", "KD_CONNECTION", "/path/.kd/config.yaml"
+
+
+class ConnectionOrigin(NamedTuple):
+    """Provenance of a connection entry loaded from config files."""
+
+    source: str  # "local" or "global"
+    path: str  # absolute path to the file the entry was loaded from
+
+
+class ResolvedConfig:
+    """Config resolved from all sources with per-key source tracking.
+
+    Flat keys are resolved via the standard chain (flag > local > global > default).
+    Structured sections (defaults, projects, connections) are stored as raw dicts
+    from each config file, enabling the 10-level command-option resolution chain.
+    """
+
+    def __init__(
+        self,
+        entries: dict[str, ResolvedValue],
+        *,
+        local_defaults: dict[str, dict[str, Any]] | None = None,
+        global_defaults: dict[str, dict[str, Any]] | None = None,
+        local_projects: dict[str, Any] | None = None,
+        global_projects: dict[str, Any] | None = None,
+        local_flat: dict[str, Any] | None = None,
+        global_flat: dict[str, Any] | None = None,
+        local_aliases: dict[str, str] | None = None,
+        global_aliases: dict[str, str] | None = None,
+        connections: dict[str, ConnectionConfig] | None = None,
+        connection_origins: dict[str, ConnectionOrigin] | None = None,
+        default_connection_name: str | None = None,
+        connection_defaults: dict[str, dict[str, Any]] | None = None,
+        connection_flat: dict[str, Any] | None = None,
+    ) -> None:
+        self._entries = dict(entries)
+        self._local_defaults = local_defaults or {}
+        self._global_defaults = global_defaults or {}
+        self._local_projects = local_projects or {}
+        self._global_projects = global_projects or {}
+        self._local_flat = local_flat or {}
+        self._global_flat = global_flat or {}
+        self._local_aliases = local_aliases or {}
+        self._global_aliases = global_aliases or {}
+        self._connections = connections or {}
+        self._connection_origins = connection_origins or {}
+        self._default_connection_name = default_connection_name
+        self._connection_defaults = connection_defaults or {}
+        self._connection_flat = connection_flat or {}
+
+    # -- flat key accessors --------------------------------------------------
+
+    @property
+    def default_project(self) -> str | None:
+        rv = self._entries.get("default_project")
+        return rv.value if rv else None
+
+    @property
+    def output(self) -> str:
+        rv = self._entries.get("output")
+        return rv.value if rv else "table"
+
+    @property
+    def limit(self) -> int:
+        rv = self._entries.get("limit")
+        if rv:
+            try:
+                return int(rv.value)
+            except (ValueError, TypeError):
+                return 50
+        return 50
+
+    @property
+    def debug(self) -> bool:
+        rv = self._entries.get("debug")
+        if rv:
+            return rv.value.lower() in ("true", "1", "yes")
+        return False
+
+    # -- dict-like access ----------------------------------------------------
+
+    def get(self, key: str) -> ResolvedValue | None:
+        return self._entries.get(key)
+
+    @property
+    def entries(self) -> dict[str, ResolvedValue]:
+        """Read-only view of all resolved entries."""
+        return dict(self._entries)
+
+    # -- connection accessors -----------------------------------------------
+
+    @property
+    def connections(self) -> dict[str, ConnectionConfig]:
+        return self._connections
+
+    @property
+    def connection_origins(self) -> dict[str, ConnectionOrigin]:
+        """Provenance per connection: ``source`` (local/global) and ``path``."""
+        return self._connection_origins
+
+    @property
+    def default_connection_name(self) -> str | None:
+        return self._default_connection_name
+
+    @property
+    def connection_defaults(self) -> dict[str, dict[str, Any]]:
+        return self._connection_defaults
+
+    @property
+    def connection_flat(self) -> dict[str, Any]:
+        return self._connection_flat
+
+    # -- structured section accessors ----------------------------------------
+
+    @property
+    def local_defaults(self) -> dict[str, dict[str, Any]]:
+        return self._local_defaults
+
+    @property
+    def global_defaults(self) -> dict[str, dict[str, Any]]:
+        return self._global_defaults
+
+    @property
+    def local_projects(self) -> dict[str, Any]:
+        return self._local_projects
+
+    @property
+    def global_projects(self) -> dict[str, Any]:
+        return self._global_projects
+
+    @property
+    def local_flat(self) -> dict[str, Any]:
+        return self._local_flat
+
+    @property
+    def global_flat(self) -> dict[str, Any]:
+        return self._global_flat
+
+    @property
+    def local_aliases(self) -> dict[str, str]:
+        return self._local_aliases
+
+    @property
+    def global_aliases(self) -> dict[str, str]:
+        return self._global_aliases
+
+    @property
+    def aliases(self) -> dict[str, str]:
+        """Merged aliases: global first, local overrides."""
+        merged = dict(self._global_aliases)
+        merged.update(self._local_aliases)
+        return merged
+
+
+# ---------------------------------------------------------------------------
+# Directory walk
+# ---------------------------------------------------------------------------
+
+
+def find_local_config(start: Path | None = None) -> Path | None:
+    """Walk up from *start* to filesystem root, return first ``.kd/config.yaml`` found."""
+    current = (start or Path.cwd()).resolve()
+    while True:
+        candidate = current / ".kd" / "config.yaml"
+        if candidate.is_file():
+            return candidate
+        parent = current.parent
+        if parent == current:  # filesystem root
+            return None
+        current = parent
+
+
+# ---------------------------------------------------------------------------
+# Data model (single-file)
+# ---------------------------------------------------------------------------
+
+
+class ProjectConfig(BaseModel):
+    """Per-project configuration: field aliases and scoped defaults."""
+
+    field_aliases: dict[str, str] = {}
+    defaults: dict[str, dict[str, Any]] = {}
+
+
+class HistoryConfig(BaseModel):
+    """Copy-on-write snapshot settings."""
+
+    retention: int = 20
+
+
+class YtctlConfig(BaseModel):
+    """Configuration model.
+
+    Connection-first: ``default_connection`` + ``connections:`` replace
+    the former flat ``url``/``token``/``default_project`` keys.
+    Global ``output``/``limit``/``debug`` are fallbacks for connections
+    that don't specify their own.
+    """
+
+    # Connection routing
+    default_connection: str | None = None
+    connections: dict[str, ConnectionConfig] = {}
+
+    # Global flat keys (fallbacks for all connections)
+    output: str = "table"
+    limit: int = 50
+    debug: bool = False
+
+    # Structured sections
+    defaults: dict[str, dict[str, Any]] = {}
+    projects: dict[str, ProjectConfig] = {}
+    aliases: dict[str, str] = {}
+    history: HistoryConfig = HistoryConfig()
+
+
+def load_config(path: Path | None = None) -> YtctlConfig:
+    """Load config from YAML file. Returns empty config if file doesn't exist."""
+    config_path = path or DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        return YtctlConfig()
+    try:
+        raw = yaml.safe_load(config_path.read_text()) or {}
+        return YtctlConfig(**raw)
+    except (yaml.YAMLError, TypeError, ValueError) as e:
+        raise ConfigError(f"Invalid config at {config_path}: {e}") from e
+
+
+def save_config(config: YtctlConfig, path: Path | None = None) -> None:
+    """Save config to YAML file. Creates parent directories if needed.
+
+    Snapshots the current file before writing (copy-on-write) and uses
+    atomic writes to prevent partial-write corruption.
+    """
+    from kd.history import atomic_write_text, snapshot_before_write
+
+    config_path = path or DEFAULT_CONFIG_PATH
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    snapshot_before_write(config_path, retention=config.history.retention)
+    data = config.model_dump(exclude_none=True)
+    # Exclude history section when at default to keep config files clean
+    if data.get("history") == HistoryConfig().model_dump():
+        data.pop("history", None)
+    atomic_write_text(config_path, yaml.dump(data, default_flow_style=False, sort_keys=False))
+
+
+# Flat keys settable via `config set` (excludes structured sections and connections)
+FLAT_KEYS = ("default_connection", "output", "limit", "debug")
+
+
+def update_config(key: str, value: str, path: Path | None = None) -> None:
+    """Update a single flat config key and save.
+
+    Validates that the key is a known flat key (not a structured section).
+    Connection-level values are not settable through this function.
+    """
+    config = load_config(path)
+    if key not in FLAT_KEYS:
+        valid_keys = ", ".join(FLAT_KEYS)
+        raise ConfigError(f"Unknown config key: {key}. Valid keys: {valid_keys}")
+    # Coerce types for non-string flat keys
+    if key == "limit":
+        try:
+            setattr(config, key, int(value))
+        except ValueError:
+            raise ConfigError(f"Invalid integer for limit: {value}") from None
+    elif key == "debug":
+        setattr(config, key, value.lower() in ("true", "1", "yes"))
+    else:
+        setattr(config, key, value)
+    save_config(config, path)
+
+
+# ---------------------------------------------------------------------------
+# Hierarchical resolution
+# ---------------------------------------------------------------------------
+
+
+def _load_raw_yaml(path: Path) -> dict[str, str]:
+    """Load raw YAML dict from a config file. Returns empty dict if missing."""
+    if not path.exists():
+        return {}
+    try:
+        return yaml.safe_load(path.read_text()) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def resolve_config(
+    *,
+    flags: dict[str, str] | None = None,
+    start_path: Path | None = None,
+    debug_log: DebugLog | None = None,
+) -> ResolvedConfig:
+    """Resolve config from all sources in priority order.
+
+    Per flat key: CLI flag → local config → global config → default.
+    Connections are merged from global then local (local overrides by name).
+    The active connection's ``default_project`` is injected into entries.
+    """
+    flags = flags or {}
+    d = debug_log or DebugLog()
+
+    # Load raw YAML dicts (not Pydantic) to distinguish explicit values from defaults
+    local_path = find_local_config(start_path)
+    local_raw = _load_raw_yaml(local_path) if local_path else {}
+    global_raw = _load_raw_yaml(DEFAULT_CONFIG_PATH)
+
+    d.trace("config", f"local config path: {local_path or 'not found'}")
+    d.trace("config", f"global config path: {DEFAULT_CONFIG_PATH}")
+
+    # Flat keys that have built-in defaults
+    _DEFAULTS: dict[str, str] = {
+        "output": "table",
+        "limit": "50",
+        "debug": "false",
+    }
+
+    # Only resolve flat keys (not structured sections or connections)
+    _FLAT_KEYS = {"default_connection", "output", "limit", "debug"}
+
+    entries: dict[str, ResolvedValue] = {}
+
+    for key in _FLAT_KEYS:
+        # 1. CLI flag
+        if key in flags and flags[key]:
+            d.trace("config", f"flag: {key} -> {flags[key]}")
+            origin = _FLAG_ORIGINS.get(key, f"--{key}")
+            entries[key] = ResolvedValue(flags[key], ConfigSource.FLAG, origin)
+            _log_resolved(d, key, flags[key], ConfigSource.FLAG)
+            continue
+        d.trace("config", f"flag: {key} -> not set")
+
+        # 2. Environment variable
+        env_var = _ENV_MAP.get(key)
+        if env_var:
+            env_val = os.environ.get(env_var)
+            if env_val:
+                d.trace("config", f"env: {env_var} -> {env_val}")
+                entries[key] = ResolvedValue(env_val, ConfigSource.ENV, env_var)
+                _log_resolved(d, key, env_val, ConfigSource.ENV)
+                continue
+            d.trace("config", f"env: {env_var} -> not set")
+        else:
+            d.trace("config", f"env: (no env var for {key})")
+
+        # 3. Local config (raw YAML — only keys explicitly in the file)
+        if key in local_raw and local_raw[key] is not None:
+            val = str(local_raw[key])
+            d.trace("config", f"local: {local_path} -> {key}={val}")
+            entries[key] = ResolvedValue(val, ConfigSource.LOCAL, str(local_path))
+            _log_resolved(d, key, val, ConfigSource.LOCAL)
+            continue
+        d.trace("config", f"local: {key} -> not set")
+
+        # 4. Global config (raw YAML)
+        if key in global_raw and global_raw[key] is not None:
+            val = str(global_raw[key])
+            d.trace("config", f"global: {DEFAULT_CONFIG_PATH} -> {key}={val}")
+            entries[key] = ResolvedValue(val, ConfigSource.GLOBAL, str(DEFAULT_CONFIG_PATH))
+            _log_resolved(d, key, val, ConfigSource.GLOBAL)
+            continue
+        d.trace("config", f"global: {key} -> not set")
+
+        # 5. Built-in default
+        if key in _DEFAULTS:
+            default_val = _DEFAULTS[key]
+            d.trace("config", f"default: {key}={default_val}")
+            entries[key] = ResolvedValue(default_val, ConfigSource.DEFAULT, "default")
+            _log_resolved(d, key, default_val, ConfigSource.DEFAULT)
+
+    # -- Connections: merge global then local (local overrides by name) ------
+    connections, connection_origins = _resolve_connections(
+        global_raw, local_raw, DEFAULT_CONFIG_PATH, local_path, d
+    )
+    default_conn_name = entries.get("default_connection")
+    default_conn_name_str = default_conn_name.value if default_conn_name else None
+
+    # Inject default_project from active connection into entries
+    conn_defaults: dict[str, dict[str, Any]] = {}
+    conn_flat: dict[str, Any] = {}
+    if connections and default_conn_name_str:
+        active = connections.get(default_conn_name_str)
+        if active:
+            if active.default_project:
+                entries["default_project"] = ResolvedValue(
+                    active.default_project,
+                    ConfigSource.GLOBAL,
+                    f"connection:{default_conn_name_str}",
+                )
+            conn_defaults = active.defaults
+            if active.output is not None:
+                conn_flat["output"] = active.output
+            if active.limit is not None:
+                conn_flat["limit"] = active.limit
+    elif connections and not default_conn_name_str and len(connections) == 1:
+        # Single connection — use it implicitly
+        single_name = next(iter(connections))
+        default_conn_name_str = single_name
+        active = connections[single_name]
+        if active.default_project:
+            entries["default_project"] = ResolvedValue(
+                active.default_project, ConfigSource.GLOBAL, f"connection:{single_name}"
+            )
+        conn_defaults = active.defaults
+        if active.output is not None:
+            conn_flat["output"] = active.output
+        if active.limit is not None:
+            conn_flat["limit"] = active.limit
+
+    # Extract structured sections from raw YAML
+    local_defaults = _extract_defaults(local_raw)
+    global_defaults = _extract_defaults(global_raw)
+    local_projects = _extract_projects(local_raw)
+    global_projects = _extract_projects(global_raw)
+    local_aliases = _extract_aliases(local_raw)
+    global_aliases = _extract_aliases(global_raw)
+
+    # Extract flat-only keys for command option resolution (levels 5/9)
+    local_flat = {k: v for k, v in local_raw.items() if k in _FLAT_KEYS and v is not None}
+    global_flat = {k: v for k, v in global_raw.items() if k in _FLAT_KEYS and v is not None}
+
+    if local_defaults or local_projects:
+        d.debug(
+            "config",
+            f"local structured: {len(local_defaults)} defaults, {len(local_projects)} projects",
+        )
+    if global_defaults or global_projects:
+        d.debug(
+            "config",
+            f"global structured: {len(global_defaults)} defaults, {len(global_projects)} projects",
+        )
+    if local_aliases or global_aliases:
+        d.debug(
+            "config",
+            f"aliases: {len(local_aliases)} local, {len(global_aliases)} global",
+        )
+    if connections:
+        d.debug("config", f"connections: {len(connections)} ({', '.join(connections)})")
+
+    return ResolvedConfig(
+        entries,
+        local_defaults=local_defaults,
+        global_defaults=global_defaults,
+        local_projects=local_projects,
+        global_projects=global_projects,
+        local_flat=local_flat,
+        global_flat=global_flat,
+        local_aliases=local_aliases,
+        global_aliases=global_aliases,
+        connections=connections,
+        connection_origins=connection_origins,
+        default_connection_name=default_conn_name_str,
+        connection_defaults=conn_defaults,
+        connection_flat=conn_flat,
+    )
+
+
+def _log_resolved(d: DebugLog, key: str, value: str, source: ConfigSource) -> None:
+    """Log the winning resolution for a config key."""
+    if key == "default_connection":
+        d.info("config", f"{key}={value} ({source})")
+    else:
+        d.debug("config", f"{key}={value} ({source})")
+
+
+def _resolve_connections(
+    global_raw: dict[str, Any],
+    local_raw: dict[str, Any],
+    global_path: Path,
+    local_path: Path | None,
+    d: DebugLog,
+) -> tuple[dict[str, ConnectionConfig], dict[str, ConnectionOrigin]]:
+    """Merge and validate connections from global and local config.
+
+    Global connections load first; local connections override by name.
+    Returns the validated connections and a parallel origin dict so the
+    caller can report which file each connection was loaded from.
+    """
+    merged: dict[str, Any] = {}
+    origins: dict[str, ConnectionOrigin] = {}
+
+    # Global first so local overrides (both by name and origin).
+    sources: list[tuple[str, dict[str, Any], Path | None]] = [
+        ("global", global_raw, global_path),
+        ("local", local_raw, local_path),
+    ]
+    for source_label, raw, path in sources:
+        conns = raw.get("connections")
+        if not isinstance(conns, dict):
+            continue
+        for name, data in conns.items():
+            if isinstance(data, dict) and path is not None:
+                merged[str(name)] = data
+                origins[str(name)] = ConnectionOrigin(source=source_label, path=str(path))
+                d.trace("config", f"connection '{name}' from {source_label} ({path})")
+
+    if not merged:
+        return {}, {}
+
+    result: dict[str, ConnectionConfig] = {}
+    for name, data in merged.items():
+        try:
+            result[name] = ConnectionConfig(**data)
+        except (TypeError, ValueError) as e:
+            raise ConfigError(f"Invalid connection '{name}': {e}") from e
+
+    return result, origins
+
+
+def _extract_defaults(raw: dict[str, Any]) -> dict[str, dict[str, Any]]:
+    """Extract the ``defaults:`` section from raw YAML, validating structure."""
+    defaults = raw.get("defaults")
+    if not isinstance(defaults, dict):
+        return {}
+    result: dict[str, dict[str, Any]] = {}
+    for cmd_key, opts in defaults.items():
+        if isinstance(opts, dict):
+            result[str(cmd_key)] = {str(k): v for k, v in opts.items()}
+    return result
+
+
+def _extract_projects(raw: dict[str, Any]) -> dict[str, Any]:
+    """Extract the ``projects:`` section from raw YAML, validating structure."""
+    projects = raw.get("projects")
+    if not isinstance(projects, dict):
+        return {}
+    result: dict[str, Any] = {}
+    for proj_key, proj_data in projects.items():
+        if isinstance(proj_data, dict):
+            result[str(proj_key)] = proj_data
+    return result
+
+
+def _extract_aliases(raw: dict[str, Any]) -> dict[str, str]:
+    """Extract the ``aliases:`` section from raw YAML, validating structure."""
+    aliases = raw.get("aliases")
+    if not isinstance(aliases, dict):
+        return {}
+    result: dict[str, str] = {}
+    for name, command in aliases.items():
+        if isinstance(command, str):
+            result[str(name)] = command
+    return result
+
+
+# Keys that exist as both flat config keys and command/output options.
+# These participate in levels 5/7 of the command option resolution chain.
+_FLAT_OPTION_KEYS = {"limit", "output"}
+
+
+def resolve_command_defaults(
+    command_key: str,
+    project: str | None,
+    raw_options: dict[str, Any],
+    config: ResolvedConfig,
+    declarations: list[OptionDeclaration],
+    *,
+    debug_log: DebugLog | None = None,
+) -> dict[str, Any]:
+    """Resolve command option defaults from the config hierarchy.
+
+    Returns a dict of option values for options **not** present in
+    *raw_options* (CLI flags always win — level 1).
+
+    Resolution per option (first non-None wins):
+
+    1. CLI flag — skipped (present in *raw_options*)
+    2. Env var — N/A for command options
+    3. Project command default — ``projects.<proj>.defaults.<cmd>.<opt>``
+    4. Local command default — ``defaults.<cmd>.<opt>`` in local config
+    5. Local flat key — for ``limit``/``output`` only
+    6. Connection command default — ``connections.<name>.defaults.<cmd>.<opt>``
+    7. Connection flat key — for ``limit``/``output`` only
+    8. Global command default — ``defaults.<cmd>.<opt>`` in global config
+    9. Global flat key — for ``limit``/``output`` only
+    10. Built-in default — from ``OptionDeclaration.default``
+    """
+    d = debug_log or DebugLog()
+    resolved: dict[str, Any] = {}
+
+    for decl in declarations:
+        opt = decl.name
+
+        # Level 1: CLI flag already set — skip
+        if opt in raw_options:
+            continue
+
+        value = _resolve_single_option(opt, command_key, project, config, d)
+        if value is not None:
+            resolved[opt] = value
+
+    return resolved
+
+
+def _resolve_single_option(
+    opt: str,
+    command_key: str,
+    project: str | None,
+    config: ResolvedConfig,
+    d: DebugLog,
+) -> Any:
+    """Walk levels 3–9 for a single option. Returns None if no config value found."""
+    # Level 3: Project command default (local then global)
+    if project:
+        val = _project_command_default(project, command_key, opt, config.local_projects)
+        if val is not None:
+            d.debug("config", f"option {opt}: project({project}).local.{command_key} -> {val}")
+            return val
+        val = _project_command_default(project, command_key, opt, config.global_projects)
+        if val is not None:
+            d.debug("config", f"option {opt}: project({project}).global.{command_key} -> {val}")
+            return val
+
+    # Level 4: Local command default
+    val = config.local_defaults.get(command_key, {}).get(opt)
+    if val is not None:
+        d.debug("config", f"option {opt}: local.defaults.{command_key} -> {val}")
+        return val
+
+    # Level 5: Local flat key (only for limit/output)
+    if opt in _FLAT_OPTION_KEYS:
+        val = config.local_flat.get(opt)
+        if val is not None:
+            d.debug("config", f"option {opt}: local.flat -> {val}")
+            return val
+
+    # Level 6: Connection command default
+    val = config.connection_defaults.get(command_key, {}).get(opt)
+    if val is not None:
+        d.debug("config", f"option {opt}: connection.defaults.{command_key} -> {val}")
+        return val
+
+    # Level 7: Connection flat key (only for limit/output)
+    if opt in _FLAT_OPTION_KEYS:
+        val = config.connection_flat.get(opt)
+        if val is not None:
+            d.debug("config", f"option {opt}: connection.flat -> {val}")
+            return val
+
+    # Level 8: Global command default
+    val = config.global_defaults.get(command_key, {}).get(opt)
+    if val is not None:
+        d.debug("config", f"option {opt}: global.defaults.{command_key} -> {val}")
+        return val
+
+    # Level 9: Global flat key (only for limit/output)
+    if opt in _FLAT_OPTION_KEYS:
+        val = config.global_flat.get(opt)
+        if val is not None:
+            d.debug("config", f"option {opt}: global.flat -> {val}")
+            return val
+
+    # Level 10: Built-in default handled by OptionRegistry.resolve() already
+    return None
+
+
+def _project_command_default(
+    project: str,
+    command_key: str,
+    opt: str,
+    projects_raw: dict[str, Any],
+) -> Any:
+    """Look up a project command default from a raw projects dict."""
+    proj_data = projects_raw.get(project)
+    if not isinstance(proj_data, dict):
+        return None
+    defaults = proj_data.get("defaults")
+    if not isinstance(defaults, dict):
+        return None
+    cmd_defaults = defaults.get(command_key)
+    if not isinstance(cmd_defaults, dict):
+        return None
+    return cmd_defaults.get(opt)
+
+
+# ---------------------------------------------------------------------------
+# Project init
+# ---------------------------------------------------------------------------
+
+
+class InitResult(NamedTuple):
+    """Result of init_project_config()."""
+
+    created: Path
+    gitignore_action: str  # "added", "already_ignored", "no_git", "created"
+
+
+def _find_git_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a ``.git`` directory."""
+    current = start.resolve()
+    while True:
+        if (current / ".git").is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+_GITIGNORE_PATTERNS = {".kd/", ".kd", "/.kd/", "/.kd"}
+
+
+def _manage_gitignore(directory: Path) -> str:
+    """Ensure ``.kd/`` is in ``.gitignore``. Returns action taken."""
+    git_root = _find_git_root(directory)
+    if git_root is None:
+        return "no_git"
+
+    gitignore = git_root / ".gitignore"
+    if gitignore.exists():
+        content = gitignore.read_text()
+        lines = {line.strip() for line in content.splitlines()}
+        if lines & _GITIGNORE_PATTERNS:
+            return "already_ignored"
+        # Append with a trailing newline if file doesn't end with one
+        sep = "" if content.endswith("\n") else "\n"
+        gitignore.write_text(f"{content}{sep}\n# kd local config\n.kd/\n")
+        return "added"
+
+    gitignore.write_text("# kd local config\n.kd/\n")
+    return "created"
+
+
+def init_project_config(
+    directory: Path | None = None,
+    url: str | None = None,
+) -> InitResult:
+    """Scaffold ``.kd/config.yaml`` in *directory* (default: cwd).
+
+    Loads the config template from package resources, optionally fills
+    the URL, and manages ``.gitignore`` for the nearest git root.
+
+    Raises ConfigError if ``.kd/config.yaml`` already exists.
+    """
+    import importlib.resources
+
+    target_dir = (directory or Path.cwd()).resolve()
+    config_dir = target_dir / ".kd"
+    config_path = config_dir / "config.yaml"
+
+    if config_path.exists():
+        raise ConfigError(f"Config already exists at {config_path}")
+
+    # Load template from package resources
+    template = (
+        importlib.resources.files("kd.resources")
+        .joinpath("config-template.yaml")
+        .read_text(encoding="utf-8")
+    )
+
+    # Pre-fill URL: uncomment connection block and fill URL
+    if url:
+        template = template.replace("# default_connection: main", "default_connection: main")
+        template = template.replace(
+            "# connections:\n"
+            "#   main:\n"
+            "#     provider: youtrack\n"
+            "#     url: https://your-instance.youtrack.cloud\n"
+            "#     # token_cmd: gopass show -o path/to/token\n"
+            "#     token_env: KD_TOKEN",
+            "connections:\n"
+            "  main:\n"
+            "    provider: youtrack\n"
+            f"    url: {url}\n"
+            "    # token_cmd: gopass show -o path/to/token\n"
+            "    token_env: KD_TOKEN",
+        )
+
+    config_dir.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(template)
+
+    gitignore_action = _manage_gitignore(target_dir)
+
+    return InitResult(created=config_path, gitignore_action=gitignore_action)