dotagents-cli 0.3.0__py3-none-any.whl

dotagents/_scope.py

@@ -0,0 +1,265 @@
+"""Scope and overlay-source resolution for ``dotagents overlays``.
+
+Two orthogonal axes the ``overlays`` command needs, kept out of ``cli.py`` (which
+only wires args) to match ``_overlays.py`` / ``_skills.py`` / ``_sync.py``:
+
+* **Scope** -- *where installed overlays live*. ``user`` is ``<agents_dir>/`` (the
+  configurable store, default ``~/.agents``); ``project`` is ``<project>/.agents/``.
+  An overlay installs into ``<scope>/overlays/<name>/`` and skills publish into the
+  shared ``<scope>/skills/``. There is no registry file: installed overlays are
+  **discovered** by their presence under ``overlays/`` (the locked "discover, don't
+  track" decision). A ``system`` tier (``/etc/agents``) is designed-for but not built.
+
+* **Source** -- *where an overlay to install comes from*. ``resolve_source`` returns
+  an ``OverlaySource`` whose ``.root`` is a local directory of ``<name>/`` overlay
+  dirs. The default is the bundled ``overlays/`` (resolved ``.pyz``-safe via
+  ``importlib.resources``, mirroring ``cli._package_data_dir``); an explicit
+  ``--source`` / ``$AGENTS_OVERLAYS_SRC`` overrides it. A git/URI source is a
+  *later* swap of the resolver's default -- ``resolve_source`` is the single
+  extension point (clone/pull into a cache, then hand back a local ``.root``), so a
+  repo source drops in with **no** change to the command classes.
+
+Never print ``DOTAGENTS_*`` values (Leakage): this module reads the env var but
+only ever reports the resolved path, never the raw value.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+#: A directory under ``overlays/`` is an overlay IFF its name matches this: a
+#: leading ASCII letter, then ASCII letters/digits/``_``/``.``/``-``. A dot is
+#: allowed MID-name (``foo.bar``, ``v1.2``) but not as the first char, so
+#: ``.git``/``.hidden`` are excluded; a leading underscore (``__pycache__``) and
+#: a leading digit (``2fast``) are excluded too. One shared rule for
+#: ``discover_overlays``, the ``get_file_paths`` overlay gate (`_resolve.py`), and
+#: ``overlays add`` (D84). (Whether a path IS a directory is checked separately
+#: with ``is_dir()``, which follows symlinks -- a symlink-to-dir is a valid overlay.)
+_OVERLAY_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_.-]*$")
+
+
+def is_valid_overlay_name(name: str) -> bool:
+    """A dir under ``overlays/`` is an overlay iff its name matches: a leading ASCII
+    letter, then ASCII letters/digits/``_``/``.``/``-``. Dots are allowed mid-name
+    (``foo.bar``, ``v1.2``) but NOT as the first char, so ``.git``/``.hidden`` and
+    ``__pycache__`` (leading ``_``) and ``2fast`` (leading digit) are excluded."""
+    return bool(_OVERLAY_NAME_RE.match(name))
+
+
+def normalize_overlay_name(name: str) -> str:
+    """Overlay names normalize to lowercase-dash for matching (precursor rule):
+    ``name.lower().replace('_', '-')``. So ``My_Overlay`` and ``my-overlay`` are
+    the same overlay."""
+    return name.lower().replace("_", "-")
+
+
+class Scope:
+    """A resolved install scope: the roots overlays and skills live under.
+
+    ``user`` -> ``<agents_dir>/`` (the configurable store, default ``~/.agents``).
+    ``project`` -> ``<project_root>/.agents/``. The ``overlays/`` and ``skills/``
+    subdirs beneath ``agents_root`` are the discover-and-publish surfaces.
+    """
+
+    def __init__(self, level: str, agents_root: Path):
+        self.level = level
+        self.agents_root = Path(agents_root)
+
+    @property
+    def overlay_root(self) -> Path:
+        return self.agents_root / "overlays"
+
+    @property
+    def shared_skills_dir(self) -> Path:
+        return self.agents_root / "skills"
+
+    @property
+    def cmds_dir(self) -> Path:
+        """Directory of discovered command modules for this scope (D76).
+
+        ``<agents_root>/dotagents/cmds`` -- a seam alongside ``overlays``/``skills``.
+        ``init``/``install`` lay the bundled command modules here, and
+        ``dotagents.cli._discover`` runs ``duho.discover_commands`` over it (per
+        scope, user + project) so a user's own ``*.py`` command modules dropped
+        beside them are picked up with zero config."""
+        return self.agents_root / "dotagents" / "cmds"
+
+    def overlay_dir(self, name: str) -> Path:
+        return self.overlay_root / name
+
+    def __repr__(self) -> str:
+        return "Scope(%s, root=%s)" % (self.level, self.agents_root)
+
+
+def resolve_scope(
+    global_scope: bool = False,
+    *,
+    agents_dir: "str | os.PathLike | None" = None,
+    project_root: "str | os.PathLike | None" = None,
+) -> Scope:
+    """Pick the install scope.
+
+    ``-g/--global`` forces the **user** scope (``agents_dir``, default ``~/.agents``).
+    Otherwise the scope is **project**, rooted at (in precedence order): an explicit
+    ``project_root`` argument, else ``$AGENTS_PROJECT_ROOT`` if set, else the current
+    directory. ``$AGENTS_PROJECT_ROOT`` lets a harness (or ``dotagents env``) pin the
+    project root once so every command agrees on it regardless of the cwd a subprocess
+    happens to run in; ``<root>/.agents/`` is where this project's overlays live. The
+    store location is configurable (D58): ``agents_dir`` comes from the caller
+    (``--agents-dir``) or defaults to ``~/.agents``; never hardcoded past that default.
+    """
+    root = Path(agents_dir).expanduser() if agents_dir else (Path.home() / ".agents")
+    if global_scope:
+        return Scope("user", root)
+    proj = Path(project_root).expanduser() if project_root else project_root_default()
+    return Scope("project", proj / ".agents")
+
+
+#: Agent-native project-root vars, consulted (in order) as a fallback for
+#: ``AGENTS_PROJECT_ROOT``. A harness that already exposes its workspace root lets
+#: dotagents pick it up without the user setting anything. As of 2026-07, Claude
+#: Code's ``CLAUDE_PROJECT_DIR`` is the ONLY one any major harness sets (and only in
+#: hook / stdio-MCP / plugin-LSP contexts, not its Bash tool) -- Gemini/Codex/Cursor/
+#: Copilot/aider all rely on cwd + internal git-root detection and export nothing.
+#: Extend this tuple as other harnesses adopt one.
+_HARNESS_PROJECT_ROOT_VARS = ("CLAUDE_PROJECT_DIR",)
+
+
+def project_root_default() -> Path:
+    """The project root when none is passed explicitly, in precedence order:
+    ``$AGENTS_PROJECT_ROOT`` (dotagents' canonical var) -> a known agent-native var
+    (:data:`_HARNESS_PROJECT_ROOT_VARS`, e.g. Claude Code's ``CLAUDE_PROJECT_DIR``)
+    -> the current working directory.
+
+    Emitting ``AGENTS_PROJECT_ROOT`` (see ``dotagents env``) lets every command and
+    subprocess agree on one root regardless of the cwd it happens to run in."""
+    for var in ("AGENTS_PROJECT_ROOT", *_HARNESS_PROJECT_ROOT_VARS):
+        value = os.environ.get(var)
+        if value:
+            return Path(value).expanduser()
+    return Path.cwd()
+
+
+def discover_overlays(scope: Scope) -> "list[str]":
+    """Installed overlay names in this scope -- the presence of ``overlays/<name>/``.
+
+    No registry: a directory under ``<scope>/overlays/`` *is* an installed overlay
+    (manifest or not) as long as its name is a valid overlay name
+    (:func:`is_valid_overlay_name` -- so ``.git``/``__pycache__``/dotfiles are
+    skipped). Returns sorted names; empty if the root is absent.
+    """
+    root = scope.overlay_root
+    if not root.is_dir():
+        return []
+    return sorted(
+        p.name for p in root.iterdir() if p.is_dir() and is_valid_overlay_name(p.name)
+    )
+
+
+def filter_names(names: "list[str]", pattern: "Optional[str]") -> "list[str]":
+    """Glob-filter overlay names (``sync 'py*'``). ``None``/``'*'`` keep all."""
+    if not pattern or pattern == "*":
+        return list(names)
+    return [n for n in names if fnmatch.fnmatch(n, pattern)]
+
+
+class OverlaySource:
+    """A resolved place overlays are fetched *from* for ``add``/``sync``.
+
+    ``root`` is a local directory holding ``<name>/`` overlay dirs. ``available()``
+    lists them; ``overlay_dir(name)`` resolves one (raising if absent). This is the
+    seam a future git/URI source slots into: a ``GitOverlaySource`` would clone/pull
+    into a cache in ``__init__`` and set ``root`` to that checkout -- the command
+    classes only ever touch this interface, so they need no change.
+    """
+
+    def __init__(self, root: Path):
+        self.root = Path(root)
+
+    def available(self) -> "list[str]":
+        if not self.root.is_dir():
+            return []
+        return sorted(
+            p.name
+            for p in self.root.iterdir()
+            if p.is_dir() and not p.name.startswith(".")
+        )
+
+    def overlay_dir(self, name: str) -> Path:
+        candidate = self.root / name
+        if not candidate.is_dir():
+            raise SystemExit(
+                "error: overlay %r not found in source %s (available: %s)"
+                % (name, self.root, ", ".join(self.available()) or "none")
+            )
+        return candidate
+
+    def __repr__(self) -> str:
+        return "OverlaySource(%s)" % self.root
+
+
+#: Environment override for the default overlay source (a local directory today;
+#: a git/URI string once ``resolve_source`` grows that branch). Read, never printed.
+SOURCE_ENV = "AGENTS_OVERLAYS_SRC"
+#: back-compat: DOTAGENTS_OVERLAYS_SRC is deprecated, removable next release.
+SOURCE_ENV_LEGACY = "DOTAGENTS_OVERLAYS_SRC"
+
+
+def bundled_overlays_root() -> "Path | None":
+    """Locate the bundled example ``overlays/`` directory, ``.pyz``-safe.
+
+    Two homes, tried in order: the packaged copy (``importlib.resources`` under the
+    installed ``dotagents`` package -- extracted from a zipapp when needed, exactly
+    like ``cli._package_data_dir``), then a repo checkout's top-level ``overlays/``
+    (dev use, mirroring ``BuildPyz``'s ``parents[2]`` reach). Returns ``None`` if
+    neither exists -- a plain ``pip install`` that bundled no overlays.
+    """
+    # Prefer the shared resolver in cli so zipapp extraction is cached once.
+    try:
+        from dotagents.cli import _package_data_dir
+
+        packaged = _package_data_dir("_overlays_src")
+        if packaged is not None and packaged.is_dir():
+            return packaged
+    except Exception:
+        pass
+
+    repo_overlays = Path(__file__).resolve().parents[2] / "overlays"
+    if repo_overlays.is_dir():
+        return repo_overlays
+    return None
+
+
+def resolve_source(source: "Optional[str]" = None) -> OverlaySource:
+    """Resolve the overlay source: explicit ``--source`` / ``$AGENTS_OVERLAYS_SRC``,
+    else the bundled ``overlays/``.
+
+    Today every branch yields a **local directory** ``OverlaySource``. The single
+    extension point for a git/URI source is here: when ``raw`` looks like a URI (a
+    later change), construct a ``GitOverlaySource`` instead -- callers are unaffected
+    because they only use the returned object's ``available``/``overlay_dir``.
+    """
+    raw = (
+        source
+        or os.environ.get(SOURCE_ENV)
+        or os.environ.get(SOURCE_ENV_LEGACY)
+        or None
+    )
+    if raw:
+        # (extension point) a URI/git ``raw`` would branch to a cached clone here.
+        root = Path(raw).expanduser()
+        if not root.is_dir():
+            raise SystemExit("error: --source path is not a directory: %s" % raw)
+        return OverlaySource(root)
+
+    bundled = bundled_overlays_root()
+    if bundled is None:
+        raise SystemExit(
+            "error: no overlay source. This build bundles no overlays; pass "
+            "--source <dir> or set %s to a directory of overlays." % SOURCE_ENV
+        )
+    return OverlaySource(bundled)

dotagents/_skills.py

@@ -0,0 +1,236 @@
+"""Publish an overlay's skills into a scope's shared ``skills/`` dir, so every
+agent that reads that dir sees the same skills (the "skills synced between agents"
+behavior).
+
+An overlay may ship ``skills/<skill-name>/`` directories. Publishing symlinks (or,
+where symlinks aren't available, copies) each into ``<scope>/skills/<skill-name>/``.
+Removing an overlay unpublishes only the skills **it** published (matched against
+its own ``skills/`` source), never a skill another overlay or the user placed there,
+then sweeps any now-broken symlinks.
+
+Pure stdlib (``os``/``shutil``) -- no ``pathlib_next`` -- so it works in a plain
+``pip install`` and inside the ``.pyz``. Symlink-preferred with a copy fallback is
+the contract; ``--copy`` forces the copy path up front (Windows / no-symlink).
+
+Ported from the precursor's ``managers/skills.py`` + ``helpers.py`` sync
+primitives; the external ``skills``-CLI registry (``register``/``skills.txt``) is
+deliberately **dropped** -- publish-to-shared-dir is the stdlib, useful part.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+class SyncResult:
+    __slots__ = ("success", "mode", "message")
+
+    def __init__(self, success: bool, mode: str, message: str = ""):
+        self.success = success
+        self.mode = mode
+        self.message = message
+
+    def __bool__(self) -> bool:
+        return self.success
+
+
+def _paths_match(source: Path, target: Path) -> bool:
+    """True if ``target`` already mirrors ``source`` (same file set, by name).
+
+    A cheap structural check -- enough to decide "already published, leave it" from
+    "conflicting content, overwrite". Not a content hash: republish on ``sync`` is a
+    separate, explicit path (``resync_path``)."""
+    if not source.exists() or not target.exists():
+        return False
+    if source.is_file() and target.is_file():
+        return source.stat().st_size == target.stat().st_size
+    if source.is_dir() and target.is_dir():
+        src_files = {str(p.relative_to(source)) for p in source.rglob("*") if p.is_file()}
+        tgt_files = {str(p.relative_to(target)) for p in target.rglob("*") if p.is_file()}
+        return src_files == tgt_files
+    return False
+
+
+def _resolves_to(target: Path, source: Path) -> bool:
+    try:
+        return Path(os.path.realpath(str(target))) == source.resolve()
+    except OSError:
+        return False
+
+
+def sync_path(
+    source: Path, target: Path, *, prefer_symlink: bool = True, force: bool = False
+) -> SyncResult:
+    """Publish ``source`` at ``target`` -- symlink if possible, else copy.
+
+    An existing correct symlink / matching copy is a no-op success. A conflicting
+    target is only replaced with ``force=True``; otherwise it is reported as a
+    conflict so the caller can decide (the publish path retries once with force)."""
+    if not source.exists():
+        return SyncResult(False, "error", "source does not exist: %s" % source)
+
+    if os.path.lexists(str(target)):
+        if not force:
+            if os.path.islink(str(target)):
+                if _resolves_to(target, source):
+                    return SyncResult(True, "symlink", "already linked")
+                return SyncResult(False, "symlink", "target symlink points elsewhere")
+            if _paths_match(source, target):
+                return SyncResult(True, "copy", "already synced")
+            return SyncResult(False, "conflict", "target exists with different content")
+        _remove(target)
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if prefer_symlink:
+        try:
+            os.symlink(str(source), str(target), target_is_directory=source.is_dir())
+            return SyncResult(True, "symlink", "linked %s" % target.name)
+        except (OSError, NotImplementedError):
+            pass  # fall through to copy
+
+    try:
+        if source.is_dir():
+            shutil.copytree(str(source), str(target))
+            return SyncResult(True, "copy", "copied %s" % target.name)
+        shutil.copy2(str(source), str(target))
+        return SyncResult(True, "copy", "copied %s" % target.name)
+    except (OSError, shutil.Error) as exc:
+        return SyncResult(False, "copy", "copy failed: %s" % exc)
+
+
+def unsync_path(target: Path, source: Path) -> SyncResult:
+    """Unpublish ``target`` -- but only if it is this overlay's (a symlink to
+    ``source``, or a copy matching it). A symlink pointing elsewhere, or a copy whose
+    content differs, is left untouched (it is someone else's)."""
+    if not os.path.lexists(str(target)):
+        return SyncResult(True, "none", "does not exist")
+    if os.path.islink(str(target)):
+        if not _resolves_to(target, source):
+            return SyncResult(False, "symlink", "symlink points elsewhere")
+        os.unlink(str(target))
+        return SyncResult(True, "symlink", "removed symlink")
+    if not _paths_match(source, target):
+        return SyncResult(False, "copy", "content differs from source")
+    try:
+        _remove(target)
+        return SyncResult(True, "copy", "removed copy")
+    except OSError as exc:
+        return SyncResult(False, "copy", "removal failed: %s" % exc)
+
+
+def resync_path(source: Path, target: Path) -> SyncResult:
+    """Refresh a published skill from its overlay source. A symlink is inherently
+    current; a copy is re-copied when its file set drifted."""
+    if not source.exists():
+        return SyncResult(False, "error", "source does not exist")
+    if not os.path.lexists(str(target)):
+        return sync_path(source, target, prefer_symlink=True)
+    if os.path.islink(str(target)):
+        return SyncResult(True, "symlink", "symlink is current")
+    if _paths_match(source, target):
+        return SyncResult(True, "copy", "current")
+    return sync_path(source, target, prefer_symlink=False, force=True)
+
+
+def _remove(path: Path) -> None:
+    if os.path.islink(str(path)) or path.is_file():
+        os.unlink(str(path))
+    elif path.is_dir():
+        shutil.rmtree(str(path))
+
+
+def _prune_empty(path: Path) -> None:
+    try:
+        path.rmdir()
+    except OSError:
+        pass
+
+
+def clean_broken_syncs(shared_skills: Path, logger=None) -> None:
+    """Drop symlinks under ``shared_skills`` whose target no longer exists (an
+    overlay's ``skills/`` went away), then remove the dir if it emptied."""
+    if not shared_skills.is_dir():
+        return
+    for entry in shared_skills.iterdir():
+        if entry.name.startswith("."):
+            continue
+        if os.path.islink(str(entry)) and not entry.exists():
+            os.unlink(str(entry))
+            if logger is not None:
+                logger.info("removed broken skill sync: %s", entry.name)
+    _prune_empty(shared_skills)
+
+
+def _overlay_skill_dirs(overlay_dir: Path) -> "list[Path]":
+    skills_dir = overlay_dir / "skills"
+    if not skills_dir.is_dir():
+        return []
+    return sorted(d for d in skills_dir.iterdir() if d.is_dir())
+
+
+def publish_overlay_skills(
+    overlay_dir: Path, shared_skills: Path, *, copy: bool = False, logger=None
+) -> int:
+    """Publish each ``overlay_dir/skills/<name>/`` into ``shared_skills``.
+
+    Symlink-preferred unless ``copy`` forces copies. A conflicting target is
+    overwritten (the overlay owns its skill names). Returns the count published.
+    Sweeps broken syncs first so a stale symlink can't block a re-publish."""
+    clean_broken_syncs(shared_skills, logger=logger)
+    skill_dirs = _overlay_skill_dirs(overlay_dir)
+    if not skill_dirs:
+        return 0
+    shared_skills.mkdir(parents=True, exist_ok=True)
+    published = 0
+    for skill_dir in skill_dirs:
+        target = shared_skills / skill_dir.name
+        result = sync_path(skill_dir, target, prefer_symlink=not copy, force=False)
+        if not result and result.mode == "conflict":
+            result = sync_path(skill_dir, target, prefer_symlink=not copy, force=True)
+        if result:
+            published += 1
+            if logger is not None and "already" not in result.message:
+                logger.info("skill %s: %s", skill_dir.name, result.message)
+        elif logger is not None:
+            logger.warning("failed to publish skill %s: %s", skill_dir.name, result.message)
+    return published
+
+
+def resync_overlay_skills(overlay_dir: Path, shared_skills: Path, *, logger=None) -> int:
+    """Refresh already-published skills of this overlay (copy-mode drift). New
+    skills are published; symlinks are inherently current."""
+    skill_dirs = _overlay_skill_dirs(overlay_dir)
+    if not skill_dirs or not shared_skills.is_dir():
+        # Nothing published yet -> fall back to a fresh publish.
+        return publish_overlay_skills(overlay_dir, shared_skills, logger=logger)
+    updated = 0
+    for skill_dir in skill_dirs:
+        target = shared_skills / skill_dir.name
+        result = resync_path(skill_dir, target)
+        if result and result.mode == "copy" and "current" not in result.message:
+            updated += 1
+            if logger is not None:
+                logger.info("skill %s: %s", skill_dir.name, result.message)
+    return updated
+
+
+def remove_overlay_skills(overlay_dir: Path, shared_skills: Path, *, logger=None) -> int:
+    """Unpublish only the skills *this* overlay published (matched to its source),
+    then sweep broken syncs. Returns the count removed."""
+    if not shared_skills.is_dir():
+        return 0
+    removed = 0
+    for skill_dir in _overlay_skill_dirs(overlay_dir):
+        target = shared_skills / skill_dir.name
+        result = unsync_path(target, skill_dir)
+        if result and result.mode != "none":
+            removed += 1
+            if logger is not None:
+                logger.info("removed skill: %s (%s)", skill_dir.name, result.mode)
+        elif not result and logger is not None:
+            logger.warning("kept skill %s: %s", skill_dir.name, result.message)
+    clean_broken_syncs(shared_skills, logger=logger)
+    _prune_empty(shared_skills)
+    return removed

dotagents/_sync.py

@@ -0,0 +1,72 @@
+"""PathSyncer wrapper reproducing the legacy install.py backup/copy report.
+
+Uses pathlib_next's PathSyncer (checksum-driven one-way tree sync) instead of
+a hand-rolled read_bytes()==read_bytes() loop. On a would-overwrite of changed
+content, the hook backs the old target file up to
+<dest>/install_backup/<timestamp>/ before the sync writes, then counts
+installed/backed-up/unchanged exactly as the legacy installer's final line.
+"""
+
+import shutil
+from pathlib import Path
+
+from pathlib_next import LocalPath
+from pathlib_next.utils.sync import PathSyncer, SyncEvent
+
+
+class _Counts:
+    def __init__(self):
+        self.installed = 0
+        self.backed_up = 0
+        self.unchanged = 0
+
+
+def sync_payload(
+    src: Path,
+    dest: Path,
+    entries: "list[str]",
+    *,
+    dry_run: bool = False,
+) -> "tuple[_Counts, list[str]]":
+    """Sync a fixed list of top-level payload entries (files or dirs) from
+    `src` into `dest`, matching the legacy installer's PAYLOAD-list behavior.
+    """
+    from dotagents._merge import timestamped_backup_root
+
+    dest = Path(dest)
+    backup_root = timestamped_backup_root(dest)
+    counts = _Counts()
+    lines: "list[str]" = []
+    dest_local = LocalPath(dest)
+    copied_ids = set()
+
+    def hook(source, target, event: SyncEvent, is_dry_run: bool):
+        if event is SyncEvent.Copy:
+            rel = target.path.relative_to(dest_local)
+            existed = target.exists()
+            if existed:
+                lines.append("backup:  %s" % rel.as_posix())
+                if not is_dry_run:
+                    bak = backup_root / str(rel)
+                    bak.parent.mkdir(parents=True, exist_ok=True)
+                    shutil.copy2(str(target.path), str(bak))
+                counts.backed_up += 1
+            lines.append("install: %s" % rel.as_posix())
+            counts.installed += 1
+            copied_ids.add(id(target))
+        elif event is SyncEvent.Synced and source.is_file():
+            if target.exists() and id(target) not in copied_ids:
+                counts.unchanged += 1
+
+    syncer = PathSyncer(hook=hook)
+
+    for entry in entries:
+        source_path = Path(src) / entry
+        target_path = dest / entry
+        if not source_path.exists():
+            continue
+        if not dry_run:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+        syncer.sync(LocalPath(source_path), LocalPath(target_path), dry_run=dry_run)
+
+    return counts, lines, backup_root

dotagents/_wrappers.py

@@ -0,0 +1,112 @@
+"""Write `dotagents` / `dotagents.cmd` wrappers pointing at a built pyz."""
+
+import os
+import stat
+import sys
+from pathlib import Path
+
+POSIX_TEMPLATE = '#!/bin/sh\nexec "{python}" "{pyz}" "$@"\n'
+CMD_TEMPLATE = '@echo off\r\n"{python}" "{pyz}" %*\r\n'
+
+# Relative forms: resolve the pyz from the wrapper's own directory, so moving or
+# copying the scope dir does not break the command.
+POSIX_TEMPLATE_REL = (
+    '#!/bin/sh\nexec "{python}" "$(dirname "$0")/{pyz}" "$@"\n'
+)
+CMD_TEMPLATE_REL = '@echo off\r\n"{python}" "%~dp0{pyz}" %*\r\n'
+
+
+def write_wrappers(
+    bin_dir: Path,
+    pyz_path: Path,
+    python: "str | None" = None,
+    *,
+    relative: bool = False,
+) -> "list[Path]":
+    """Write both wrapper scripts into `bin_dir`, returning the paths written.
+
+    BOTH files are always written, on every platform: `dotagents` (sh) and
+    `dotagents.cmd`. A Windows box with Git Bash / WSL runs the sh one and cmd
+    runs the `.cmd`, and the two never collide -- cmd.exe resolves `.cmd` via
+    PATHEXT while sh picks the extensionless file. Writing only the platform's
+    "native" form (what the precursor did) breaks the other shell on the same box,
+    which on this project's own dev machine is the common case.
+
+    `python` defaults to the interpreter running this code (`sys.executable`),
+    embedded as an absolute path. A bare `python`/`python3` is NOT usable: on
+    Windows it resolves to the Microsoft Store alias stub ("Python was not
+    found...") for anyone who has not installed the Store package, so a wrapper
+    calling it exits 0 having done nothing -- which then silently breaks any hook
+    that shells out to `dotagents`.
+
+    `relative=True` points the wrapper at `pyz_path` relative to `bin_dir`
+    (`$(dirname $0)` / `%~dp0`), so a scope directory stays relocatable. Falls
+    back to an absolute path when the two live on different drives.
+    """
+    bin_dir = Path(bin_dir)
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    pyz_path = Path(pyz_path).resolve()
+    python = python or sys.executable
+
+    rel_pyz = None
+    if relative:
+        try:
+            candidate = Path(os.path.relpath(pyz_path, bin_dir))
+        except ValueError:
+            # Different drives on Windows -- no relative path exists.
+            candidate = None
+        # Relative is for a pyz living in or beside the scope (keeps the store
+        # relocatable): `dotagents.pyz` or `../dotagents.pyz`. A pyz elsewhere on
+        # disk yields a long `../../../..` chain that is unreadable and MORE
+        # fragile than absolute -- it breaks when either side moves, not just the
+        # scope. One `..` is the limit.
+        if candidate is not None and candidate.parts.count("..") <= 1:
+            rel_pyz = candidate
+
+    written = []
+
+    # `Path.write_text(..., newline=...)` needs Python 3.10+; open() directly
+    # (with newline="") so the exact \n / \r\n bytes above are preserved
+    # unchanged on every Python 3.9+ platform.
+    sh_path = bin_dir / "dotagents"
+    with open(sh_path, "w", encoding="utf-8", newline="") as f:
+        if rel_pyz is not None:
+            f.write(
+                POSIX_TEMPLATE_REL.format(
+                    python=Path(python).as_posix(), pyz=rel_pyz.as_posix()
+                )
+            )
+        else:
+            f.write(
+                POSIX_TEMPLATE.format(
+                    python=Path(python).as_posix(), pyz=pyz_path.as_posix()
+                )
+            )
+    if os.name != "nt":
+        mode = sh_path.stat().st_mode
+        sh_path.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    written.append(sh_path)
+
+    cmd_path = bin_dir / "dotagents.cmd"
+    with open(cmd_path, "w", encoding="utf-8", newline="") as f:
+        if rel_pyz is not None:
+            f.write(CMD_TEMPLATE_REL.format(python=str(python), pyz=str(rel_pyz)))
+        else:
+            f.write(CMD_TEMPLATE.format(python=str(python), pyz=str(pyz_path)))
+    written.append(cmd_path)
+
+    return written
+
+
+def check_path_warning(bin_dir: Path) -> "str | None":
+    """Return a warning string (with the literal export hint) if `bin_dir` is
+    not on PATH, else None."""
+    bin_dir = str(Path(bin_dir).resolve())
+    path_entries = [str(Path(p).resolve()) for p in os.environ.get("PATH", "").split(os.pathsep) if p]
+    if bin_dir in path_entries:
+        return None
+    if os.name == "nt":
+        hint = '$env:PATH += ";%s"' % bin_dir
+    else:
+        hint = 'export PATH="%s:$PATH"' % bin_dir
+    return "warning: %s is not on PATH. Add it with:\n  %s" % (bin_dir, hint)