coding-os 0.3.2__py3-none-any.whl

cli/_init_helpers.py

@@ -0,0 +1,587 @@
+"""Helpers for `cos init` — target resolution, name validation, git init.
+
+Separated from main.py to keep init logic testable and linear.
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from enum import IntEnum
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cli._resources import scripts_dir
+
+if TYPE_CHECKING:
+    from cli._data_types import AggregatedWorld
+
+CODING_OS_ROOT = Path(__file__).resolve().parent.parent.parent
+DEBUG_DIR = CODING_OS_ROOT / ".build" / "debug"
+DEFAULT_DEBUG_NAME = "the-script-output"
+
+NAME_REGEX = re.compile(r"^[a-z0-9][a-z0-9._-]{0,63}$")
+
+
+def is_coding_os_source_tree(project: Path) -> bool:
+    """True when `project` is the coding-os meta-repo source tree itself.
+
+    The source tree ships a hand-written AGENTS.md (CLAUDE.md symlinks to it);
+    any scaffold path (init, add/remove-stack, module toggle) must detect this
+    and refuse to clobber it. Same telltale markers used by the init guard."""
+    return (project / "src" / "core" / "thinking_os" / "server.py").exists() and (
+        project / "src" / "cli" / "main.py"
+    ).exists()
+
+
+class InitExit(IntEnum):
+    """Stable exit codes for `cos init` error paths.
+
+    FLAG_CONFLICT — mutually exclusive flags or unmet preconditions
+    TARGET_STATE  — target exists non-empty, is a file, or OS error
+    BAD_NAME      — --name does not match NAME_REGEX
+    """
+
+    FLAG_CONFLICT = 2
+    TARGET_STATE = 3
+    BAD_NAME = 4
+
+
+class InitError(ValueError):
+    """Raised when init flags / target state are invalid."""
+
+    def __init__(self, message: str, exit_code: int = InitExit.FLAG_CONFLICT) -> None:
+        super().__init__(message)
+        self.exit_code = int(exit_code)
+
+
+@dataclass(frozen=True)
+class InitTarget:
+    path: Path
+    debug: bool
+    forced_empty: bool  # True if we removed an existing non-empty dir
+    nested_in_git: bool  # True if target sits inside an existing git repo
+
+
+def validate_name(name: str) -> None:
+    """Raise InitError if `name` doesn't match the allowed regex."""
+    if not NAME_REGEX.match(name):
+        raise InitError(
+            f"invalid --name '{name}': must match ^[a-z0-9][a-z0-9._-]{{0,63}}$ "
+            "(lowercase, digits, dot/underscore/hyphen, no slashes/spaces)",
+            exit_code=InitExit.BAD_NAME,
+        )
+
+
+def _safe_remove_tree(path: Path) -> None:
+    """Remove path whether it's a regular dir, symlink, or file.
+
+    shutil.rmtree on a symlink follows the link and wipes its destination,
+    which is dangerous. Detect symlinks and unlink them instead.
+    """
+    if path.is_symlink():
+        path.unlink()
+    elif path.is_dir():
+        shutil.rmtree(path)
+    elif path.exists():
+        path.unlink()
+
+
+def _cwd_inside_coding_os(cwd: Path) -> bool:
+    """Return True if `cwd` is the coding-os source repo or inside it."""
+    try:
+        cwd.resolve().relative_to(CODING_OS_ROOT)
+        return True
+    except ValueError:
+        return False
+
+
+def _is_nested_in_git(path: Path) -> bool:
+    """Return True if `path` has a git repo as an ancestor.
+
+    Walks up from path looking for a `.git` directory. Stops at filesystem
+    root. Note: checks ancestors, not `path` itself — a fresh empty dir is
+    not considered "nested" unless a parent has `.git`.
+    """
+    for ancestor in [path, *path.parents]:
+        if ancestor == path:
+            continue
+        if (ancestor / ".git").exists():
+            return True
+    return False
+
+
+def _is_dir_empty(path: Path) -> bool:
+    return not any(path.iterdir())
+
+
+def resolve_init_target(
+    *,
+    name: str | None,
+    project_dir: str | None,
+    debug: bool,
+    force: bool,
+    cwd: Path,
+    adopt: bool = False,
+    pre_wipe_hook: object | None = None,
+) -> InitTarget:
+    """Compute the final target directory for `cos init`.
+
+    Resolution order (see plan D1/D5/D6):
+      1. --debug:
+         - must be inside coding-os repo
+         - --project-dir is mutually exclusive
+         - name = --name or DEFAULT_DEBUG_NAME
+         - target = <repo>/.build/debug/<name>
+      2. --name: parent = --project-dir or cwd, target = parent/name
+      3. --project-dir alone: target = that path
+      4. else: target = cwd
+    """
+    if debug:
+        if project_dir is not None:
+            raise InitError(
+                "--debug and --project-dir are mutually exclusive",
+                exit_code=InitExit.FLAG_CONFLICT,
+            )
+        if not _cwd_inside_coding_os(cwd):
+            raise InitError(
+                "--debug requires running inside the coding-os source repo. "
+                f"Current cwd {cwd} is outside {CODING_OS_ROOT}. "
+                "Use --project-dir instead.",
+                exit_code=InitExit.FLAG_CONFLICT,
+            )
+        effective_name = name or DEFAULT_DEBUG_NAME
+        validate_name(effective_name)
+        target = DEBUG_DIR / effective_name
+    elif name is not None:
+        validate_name(name)
+        parent = Path(project_dir).absolute() if project_dir else cwd
+        target = parent / name
+    elif project_dir is not None:
+        target = Path(project_dir).absolute()
+    else:
+        target = cwd
+
+    # Use absolute() (not resolve()) so we can detect symlinks before they
+    # collapse. Only resolve AFTER the symlink rejection check below.
+    target = target.absolute()
+
+    forced_empty = False
+    try:
+        if target.is_symlink():
+            raise InitError(
+                f"target {target} is a symlink; refusing to scaffold into symlinked paths",
+                exit_code=InitExit.TARGET_STATE,
+            )
+        if target.exists():
+            if target.is_file():
+                raise InitError(
+                    f"target {target} exists and is a file, not a directory",
+                    exit_code=InitExit.TARGET_STATE,
+                )
+            # Fire pre-wipe hook BEFORE any destructive action so the caller
+            # can refuse operations on the coding-os repo itself (or any
+            # other sentinel target) without losing files.
+            if pre_wipe_hook is not None:
+                pre_wipe_hook(target)  # type: ignore[misc]
+            # adopt overlays onto an existing repo: keep its contents in place,
+            # never refuse and never wipe (brownfield user code must survive).
+            if not _is_dir_empty(target) and not adopt:
+                if not force:
+                    raise InitError(
+                        f"target {target} is not empty. Use --force to overwrite.",
+                        exit_code=InitExit.TARGET_STATE,
+                    )
+                _safe_remove_tree(target)
+                target.mkdir(parents=True)
+                forced_empty = True
+        else:
+            target.mkdir(parents=True)
+    except OSError as exc:
+        raise InitError(
+            f"filesystem error preparing target {target}: {exc}",
+            exit_code=InitExit.TARGET_STATE,
+        ) from exc
+
+    return InitTarget(
+        path=target,
+        debug=debug,
+        forced_empty=forced_empty,
+        nested_in_git=_is_nested_in_git(target),
+    )
+
+
+@dataclass(frozen=True)
+class GitInitResult:
+    ran: bool
+    skipped_reason: str | None
+    error: str | None
+
+
+def maybe_git_init(target: InitTarget, *, enabled: bool) -> GitInitResult:
+    """Run `git init -q` unless disabled or target is nested in git.
+
+    Per plan D7/D21: nested-in-git → skip silently; command failure → WARN
+    (caller decides how to surface), not FAIL.
+    """
+    if not enabled:
+        return GitInitResult(ran=False, skipped_reason="--no-git flag", error=None)
+    if target.nested_in_git:
+        return GitInitResult(ran=False, skipped_reason="nested in existing git repo", error=None)
+    if (target.path / ".git").exists():
+        return GitInitResult(ran=False, skipped_reason="already a git repo", error=None)
+    try:
+        proc = subprocess.run(
+            ["git", "init", "-q"],
+            cwd=str(target.path),
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        return GitInitResult(ran=False, skipped_reason=None, error=str(exc))
+    if proc.returncode != 0:
+        return GitInitResult(
+            ran=False,
+            skipped_reason=None,
+            error=(proc.stderr or proc.stdout or "non-zero exit").strip(),
+        )
+    return GitInitResult(ran=True, skipped_reason=None, error=None)
+
+
+# The coding-os runtime carve-outs that MUST be present even when the project
+# already ships a baseline .gitignore (from `_base/scaffold`): the cognitive DB
+# + WAL sidecars and the rendered, machine-local adapters never enter history.
+# `ensure_gitignore` appends this block to any existing file that lacks it.
+_RUNTIME_GITIGNORE_BLOCK = """\
+# Databases (runtime — coding-os cognitive DB + WAL sidecars)
+*.db
+*.db-shm
+*.db-wal
+*.db.backup-*
+
+# coding-os runtime state — keep only the tracked config files
+.coding-os/*
+!.coding-os/rag-config.yaml
+!.coding-os/domain-config.json
+!.coding-os/scrumban-config.yaml
+
+# Rendered agent adapters — regenerated by `cos update`; they hold
+# machine-absolute symlink paths that do not survive a clone.
+.claude/
+.codex/
+.mcp.json
+"""
+
+# Mirrors the meta-repo .gitignore's runtime-ignore intent, minus the
+# meta-specific lines (web/ui build, scaffold un-ignores, golden un-ignores).
+CONSUMER_GITIGNORE = (
+    """\
+# coding-os project .gitignore — generated by `cos init`.
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+venv/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Node / frontend build output
+node_modules/
+dist/
+build/
+
+# Secrets & environment
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Editor / OS noise
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+changes.log
+
+"""
+    + _RUNTIME_GITIGNORE_BLOCK
+)
+
+_BASELINE_COMMIT_MESSAGE = "chore: scaffold coding-os project"
+
+
+def ensure_gitignore(project: Path) -> bool:
+    """Write or top up a coding-os `.gitignore`. Idempotent.
+
+    No file → write the full template. A pre-existing file (a user's own, or the
+    `_base/scaffold` baseline copied at init) is never rewritten, but the runtime
+    carve-outs are appended when absent so the cognitive DB and rendered adapters
+    never land in history regardless of the baseline's contents.
+    """
+    gitignore = project / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text(CONSUMER_GITIGNORE, encoding="utf-8")
+        return True
+    existing = gitignore.read_text(encoding="utf-8")
+    if any(line.strip() == ".coding-os/*" for line in existing.splitlines()):
+        return False
+    separator = "" if existing.endswith("\n") else "\n"
+    gitignore.write_text(existing + separator + "\n" + _RUNTIME_GITIGNORE_BLOCK, encoding="utf-8")
+    return True
+
+
+@dataclass(frozen=True)
+class InitialCommitResult:
+    committed: bool
+    skipped_reason: str | None
+    error: str | None
+
+
+def maybe_initial_commit(target: InitTarget, *, enabled: bool) -> InitialCommitResult:
+    """Stage the freshly-scaffolded tree and make one baseline commit.
+
+    Runs only when `cos init` itself created the repo (caller passes
+    `git and git_result.ran`); a nested / pre-existing repo is left
+    untouched so we never sweep a parent project's working tree. Fail-open:
+    a missing committer identity falls back to a tool identity so a headless
+    / CI consumer still gets a clean baseline; any other failure is reported
+    (WARN), never fatal.
+    """
+    if not enabled:
+        return InitialCommitResult(committed=False, skipped_reason="no fresh repo", error=None)
+    try:
+        add = subprocess.run(
+            ["git", "add", "-A"],
+            cwd=str(target.path),
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        if add.returncode != 0:
+            return InitialCommitResult(
+                committed=False,
+                skipped_reason=None,
+                error=(add.stderr or add.stdout or "git add failed").strip(),
+            )
+        commit_args = ["commit", "-q", "-m", _BASELINE_COMMIT_MESSAGE]
+        commit = subprocess.run(
+            ["git", *commit_args],
+            cwd=str(target.path),
+            capture_output=True,
+            text=True,
+            timeout=30,
+            check=False,
+        )
+        if commit.returncode != 0:
+            # Most common cause: no user.name/user.email configured. Retry
+            # once with a tool identity so the baseline always lands.
+            commit = subprocess.run(
+                [
+                    "git",
+                    "-c",
+                    "user.name=coding-os",
+                    "-c",
+                    "user.email=init@coding-os.local",
+                    *commit_args,
+                ],
+                cwd=str(target.path),
+                capture_output=True,
+                text=True,
+                timeout=30,
+                check=False,
+            )
+        if commit.returncode != 0:
+            return InitialCommitResult(
+                committed=False,
+                skipped_reason=None,
+                error=(commit.stderr or commit.stdout or "git commit failed").strip(),
+            )
+    except (FileNotFoundError, subprocess.TimeoutExpired) as exc:
+        return InitialCommitResult(committed=False, skipped_reason=None, error=str(exc))
+    return InitialCommitResult(committed=True, skipped_reason=None, error=None)
+
+
+@dataclass(frozen=True)
+class GitHooksResult:
+    installed: tuple[str, ...]
+    skipped_reason: str | None
+    error: str | None
+
+
+def install_consumer_git_hooks(project: Path, *, enabled: bool) -> GitHooksResult:
+    """Copy the human-persona git hooks into the fresh repo's .git/hooks.
+
+    The bodies resolve `.claude/.codex` hooks at runtime, so the human
+    / Codex-GUI commit path — which bypasses every PreToolUse hook — still gets
+    the doc-anchor + commit-message backstop. Never clobbers a user's existing
+    hook; fail-open — a missing body / OS error is reported, never fatal.
+    """
+    if not enabled:
+        return GitHooksResult(installed=(), skipped_reason="no fresh repo", error=None)
+    hooks_dir = project / ".git" / "hooks"
+    if not (project / ".git").is_dir():
+        return GitHooksResult(installed=(), skipped_reason="no .git", error=None)
+    pairs = (
+        ("pre-commit", scripts_dir("_pre_commit_body.sh")),
+        ("commit-msg", scripts_dir("_commit_msg_body.sh")),
+    )
+    installed: list[str] = []
+    try:
+        hooks_dir.mkdir(parents=True, exist_ok=True)
+        for name, src in pairs:
+            if not src.is_file():
+                return GitHooksResult(
+                    installed=tuple(installed),
+                    skipped_reason=None,
+                    error=f"hook body missing: {src.name}",
+                )
+            dst = hooks_dir / name
+            if dst.exists():
+                continue  # never overwrite a user-authored hook
+            shutil.copy2(src, dst)
+            dst.chmod(0o755)
+            installed.append(name)
+    except OSError as exc:
+        return GitHooksResult(installed=tuple(installed), skipped_reason=None, error=str(exc))
+    return GitHooksResult(installed=tuple(installed), skipped_reason=None, error=None)
+
+
+def ensure_agents_md(project: Path, world: AggregatedWorld) -> bool:
+    """Generate AGENTS.md from fragments if missing. Idempotent.
+
+    Returns True if the file was just created, False if it already existed.
+    Never overwrites user-customized AGENTS.md — the `if not exists` guard
+    is the contract that lets `init`, `add-adapter`, and `update` all call
+    this safely without clobbering edits.
+    """
+    from cli.renderer import render_agents_md
+    from cli.subsystems import module_state
+
+    agents_md = project / "AGENTS.md"
+    if agents_md.exists():
+        return False
+    agents_md.write_text(render_agents_md(world, module_state(project)), encoding="utf-8")
+    return True
+
+
+def materialize_makefile_targets(project: Path, state: Path, world: AggregatedWorld) -> bool:
+    """Render stack-contributed make targets into a generated include and wire
+    it into the project Makefile.
+
+    Writes `world.makefile_targets` to ``<state>/Makefile.stacks`` and ensures
+    the project Makefile pulls it in via ``-include``. Returns True if anything
+    changed. The user-authored Makefile is never rewritten beyond ensuring the
+    single include line is present — so re-running on an edited Makefile is safe.
+    """
+    from cli.renderer import render_makefile_targets
+
+    stacks_path = state / "Makefile.stacks"
+    rendered = render_makefile_targets(world)
+    changed = not stacks_path.exists() or stacks_path.read_text(encoding="utf-8") != rendered
+    if changed:
+        stacks_path.parent.mkdir(parents=True, exist_ok=True)
+        stacks_path.write_text(rendered, encoding="utf-8")
+
+    # Wire the `-include` ONLY when a stack actually contributes targets. With an
+    # empty world (e.g. the meta stack) the .stacks file is just a placeholder, so
+    # adding an include to a hand-authored Makefile would dirty it on every `cos
+    # update` for no benefit — the line appears the moment a stack first contributes.
+    makefile = project / "Makefile"
+    if makefile.exists() and world.makefile_targets:
+        state_rel = (
+            state.relative_to(project).as_posix() if state.is_relative_to(project) else state.name
+        )
+        if _ensure_stacks_include(makefile, state_rel):
+            changed = True
+    return changed
+
+
+def materialize_ci_workflow(project: Path, world: AggregatedWorld) -> bool:
+    """Render the delegating CI workflow into <project>/.github/workflows/ci.yml.
+
+    Consumer-owned and write-once (the `ensure_*` idiom): written when absent,
+    never overwritten — a `cos update` keeps any consumer edits. A world with no
+    verifiable targets renders nothing → no file.
+    """
+    from cli.renderer import render_ci_workflow
+
+    ci_path = project / ".github" / "workflows" / "ci.yml"
+    if ci_path.exists():
+        return False
+    rendered = render_ci_workflow(world)
+    if not rendered:
+        return False
+    ci_path.parent.mkdir(parents=True, exist_ok=True)
+    ci_path.write_text(rendered, encoding="utf-8")
+    return True
+
+
+def materialize_dockerfiles(project: Path, world: AggregatedWorld) -> bool:
+    """Write a Dockerfile + .dockerignore at every category=backend stack root.
+
+    World-driven (overlay + relocation aware): the backend roots come from
+    `world.anatomy`, the language from the matching verify row's glob — so a bare
+    or exempt backend (no verify row, e.g. a `*-plain` stack) gets none, like
+    frontend/mobile/library. Consumer-owned and write-once: never overwrites an
+    existing file, so a `cos update` keeps the consumer's CMD/entrypoint edits.
+    """
+    from cli.renderer import language_for_glob, render_dockerfile, render_dockerignore
+
+    language_by_root: dict[str, str] = {}
+    for row in world.verify_rows:
+        if "/**" not in row.glob:
+            continue
+        language = language_for_glob(row.glob)
+        if language:
+            language_by_root.setdefault(row.glob.split("/**", 1)[0].rstrip("/"), language)
+
+    changed = False
+    for entry in world.anatomy:
+        if entry.category != "backend":
+            continue
+        root = entry.root.rstrip("/")
+        content = render_dockerfile(language_by_root.get(root, ""))
+        if not content:
+            continue
+        base = project / root if root else project
+        for name, text in (("Dockerfile", content), (".dockerignore", render_dockerignore())):
+            target = base / name
+            if target.exists():
+                continue
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(text, encoding="utf-8")
+            changed = True
+    return changed
+
+
+def _ensure_stacks_include(makefile: Path, state_rel: str) -> bool:
+    text = makefile.read_text(encoding="utf-8")
+    if "Makefile.stacks" in text:
+        return False
+    include_line = f"-include {state_rel}/Makefile.stacks\n"
+    base_marker = f"include {state_rel}/Makefile.base\n"
+    if base_marker in text:
+        text = text.replace(base_marker, base_marker + include_line, 1)
+    else:
+        text = text.rstrip("\n") + "\n" + include_line
+    makefile.write_text(text, encoding="utf-8")
+    return True

cli/_resources.py

@@ -0,0 +1,100 @@
+"""Locate the bundled data trees (core/, adapters/, templates/, scripts/) at
+runtime — correctly under BOTH a src-layout editable install and a built wheel.
+
+The legacy `Path(__file__).parent.parent.parent / "src" / "core"` resolves the
+*source checkout* and breaks once `cos` is pip/uvx-installed (site-packages has
+no `src/` tree). Here we resolve relative to the installed `core` package so the
+same code path works in either install mode. TASK-219.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from functools import lru_cache
+from pathlib import Path
+
+
+@lru_cache(maxsize=1)
+def data_root() -> Path:
+    """Directory that CONTAINS the core/adapters/templates/scripts trees.
+
+    Source (editable) install -> `<repo>/src`; wheel install -> `site-packages`.
+    Both place `core/` directly inside this dir, so `data_root()/ "core"` etc.
+    resolve identically.
+    """
+    spec = importlib.util.find_spec("core")
+    if spec is not None and spec.origin:
+        # .../<root>/core/__init__.py  ->  <root>
+        return Path(spec.origin).resolve().parent.parent
+    # Fallback for an unusual import state: src/cli/_resources.py -> src/
+    return Path(__file__).resolve().parent.parent
+
+
+def core_dir(*parts: str) -> Path:
+    """Path under the bundled `core` tree (hooks, commands, skills, rules, ...)."""
+    return data_root().joinpath("core", *parts)
+
+
+def adapters_dir(*parts: str) -> Path:
+    """Path under the bundled `adapters` tree."""
+    return data_root().joinpath("adapters", *parts)
+
+
+def templates_dir(*parts: str) -> Path:
+    """Path under the bundled `templates` tree (per-stack scaffolds)."""
+    return data_root().joinpath("templates", *parts)
+
+
+def scripts_dir(*parts: str) -> Path:
+    """Path under the bundled `scripts` tree (git-hook bodies, installers)."""
+    return data_root().joinpath("scripts", *parts)
+
+
+# ---------------------------------------------------------------------------
+# Out-of-tree plugin overlay (community stacks / adapters) — mirrors the
+# community-skill model (skill_commands.user_skills_dir / $COS_USER_SKILLS_DIR).
+# A third party drops a stack at $COS_USER_TEMPLATES_DIR/<id>/stack.yaml or an
+# adapter at $COS_USER_ADAPTERS_DIR/<id>/adapter.yaml and the registries
+# discover it WITHOUT forking the repo. The bundled tree always wins on an id
+# collision (a community plugin may not shadow a core stack/adapter).
+# ---------------------------------------------------------------------------
+def user_templates_dir() -> Path:
+    """Out-of-tree community-stack root. Override with $COS_USER_TEMPLATES_DIR."""
+    override = os.environ.get("COS_USER_TEMPLATES_DIR")
+    return Path(override) if override else Path.home() / ".coding-os" / "templates"
+
+
+def user_adapters_dir() -> Path:
+    """Out-of-tree community-adapter root. Override with $COS_USER_ADAPTERS_DIR."""
+    override = os.environ.get("COS_USER_ADAPTERS_DIR")
+    return Path(override) if override else Path.home() / ".coding-os" / "adapters"
+
+
+def user_modules_dir() -> Path:
+    """Out-of-tree community-module (subsystem) root. Override with $COS_USER_MODULES_DIR.
+
+    A plugin author drops a `<id>.yaml` here with a `modules:` block and
+    load_subsystems() merges it over the core registry WITHOUT forking the repo
+    (the bundled tree always wins on an id collision)."""
+    override = os.environ.get("COS_USER_MODULES_DIR")
+    return Path(override) if override else Path.home() / ".coding-os" / "modules.d"
+
+
+def overlay_module_files() -> tuple[Path, ...]:
+    """User-overlay module YAML files that actually exist (see overlay_template_dirs)."""
+    d = user_modules_dir()
+    return tuple(sorted(d.glob("*.yaml"))) if d.is_dir() else ()
+
+
+def overlay_template_dirs() -> tuple[Path, ...]:
+    """User-overlay template dirs that actually exist — empty in CI / a fresh
+    install, so default-resolving them is a no-op (no test pollution)."""
+    d = user_templates_dir()
+    return (d,) if d.is_dir() else ()
+
+
+def overlay_adapter_dirs() -> tuple[Path, ...]:
+    """User-overlay adapter dirs that actually exist (see overlay_template_dirs)."""
+    d = user_adapters_dir()
+    return (d,) if d.is_dir() else ()