dotagents-cli 0.3.0__py3-none-any.whl

dotagents/cli/__init__.py

@@ -0,0 +1,354 @@
+"""dotagents CLI: init / context / env / overlays / build-pyz built-in
+subcommands, plus any user or overlay command modules discovered from a `cmds`
+directory (D76/D84).
+
+dotagents bundles NO command module of its own (D85). `link`/`sync` used to ship
+in `_overlay/dotagents/cmds/`; they are now `link-project`/`sync-project`,
+shipped -- together with their logic -- by the opt-in **private-sync** overlay,
+so plain dotagents carries no private-sync workflow. The bundled cmds DIR still
+exists and is still laid down by `init`: it is the user's documented drop-in
+point for their own commands. `leak-check` is likewise not in the repo: it
+enforces personal plan-naming conventions, so it lives in the user's private
+`.agents/dotagents/cmds/` as a discovered command module (D84).
+
+The per-command classes live in sibling modules (`cli/init.py`, `cli/overlays.py`,
+...); this package base holds the shared helpers (in `cli/_common.py`, re-exported
+here), the `Dotagents(LoggingArgs, Cli)` umbrella, `main()` (the `install.py` shim +
+`python -m dotagents` entrypoint), `_discover` (command-source resolution), and
+`_repoint_zipapp_sources` (the zipapp source-extraction shim). (`install.py` at the
+repo root is the entrypoint shim, unrelated to the removed `install` subcommand --
+`init` now lays down the base + optional `--bin-dir` wrappers, D82.)
+
+Dispatch (D76): `main()` routes through `duho.app`, not `duho.main`, so command
+discovery runs. Command MODULES are discovered from the bundled
+`_overlay/dotagents/cmds/` dir (empty by default since D85, but still a source),
+from each installed overlay's `<overlay-root>/cmds/` -- this is how the
+private-sync overlay supplies `link-project`/`sync-project` -- and from a
+per-scope `cmds` dir (one `get_file_paths` Contract-A walk, `_cmds_dirs`).
+`app`'s DEFAULT dispatch is used (dotagents has no fan-out):
+a plain `(LoggingArgs, Cmd)` class command dispatches through `app` exactly as it
+did through `main` -- `app` calls the class's `__call__`.
+
+`_compose_block` and `_package_data_dir` are re-exported at package level because
+other package modules import them as `dotagents.cli._compose_block` /
+`dotagents.cli._package_data_dir` (see `_overlays.py`, `_scope.py`).
+"""
+
+import logging
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+import duho
+from duho import Cli, LoggingArgs
+
+from dotagents import __version__
+
+# Re-export shared helpers so `dotagents.cli.<name>` keeps resolving for both the
+# command modules and external importers (`dotagents._overlays`, `dotagents._scope`).
+from dotagents.cli._common import (  # noqa: F401
+    BASE_PLAIN_FILES,
+    BASE_ROOT,
+    _apply_base,
+    _compose_block,
+    _installed_overlay_dirs,
+    _package_data_dir,
+    _resolve_from,
+    _run_overlay_setup,
+)
+
+# Import each built-in command class to register it as a compiled subcommand.
+# Importing the command modules here (never the reverse) keeps the dependency
+# edges one-directional: command modules -> cli._common / dotagents._*, and
+# cli/__init__ -> command modules. link/sync are NOT imported here -- they left
+# the package entirely (D85: the private-sync overlay ships link-project/
+# sync-project as discovered command modules; see `_discover`).
+from dotagents.cli.build_pyz import BuildPyz
+from dotagents.cli.context import Context
+from dotagents.cli.env import Env
+from dotagents.cli.init import Init
+from dotagents.cli.overlays import (  # noqa: F401  (re-exported for tests)
+    OverlayAdd,
+    OverlayList,
+    OverlayRemove,
+    OverlaySync,
+    Overlays,
+)
+
+_LOGGER = logging.getLogger("dotagents")
+
+# The compiled built-in command classes, in --help order. This is dotagents' WHOLE
+# shipped surface: link/sync left the package with their logic (D85 -- the
+# private-sync overlay supplies link-project/sync-project), leak-check is personal
+# (D84 -- the user's private `.agents/dotagents/cmds/`), and audit is repo CI
+# tooling (`tools/audit.py`), not a command. `_discover` seeds the command set
+# with these, then layers discovered commands over them (later source wins on a
+# name clash).
+_BUILTIN_COMMANDS = [
+    Init,
+    BuildPyz,
+    Context,
+    Env,
+    Overlays,
+]
+
+# The cli submodules whose sources duho introspects for flag/help definitions.
+# Every module that defines a field-bearing BUILT-IN command class must be
+# repointed inside a zipapp (see `_repoint_zipapp_sources`). DISCOVERED command
+# modules never need repointing: an overlay's cmds live on the real filesystem,
+# and the bundled cmds dir is extracted to real temp files by `_package_data_dir`
+# before import (so its `__file__` already exists -- see `_bundled_cmds_dir`).
+_COMMAND_MODULES = (
+    "dotagents.cli.init",
+    "dotagents.cli.context",
+    "dotagents.cli.env",
+    "dotagents.cli.overlays",
+    "dotagents.cli.build_pyz",
+)
+
+#: Extra env-var command search paths (os.pathsep-split), additive to the scope
+#: walk.
+CMDS_PATH_ENV = "AGENTS_CMDS_PATH"
+#: back-compat: DOTAGENTS_CMDS_PATH is deprecated, removable next release.
+CMDS_PATH_ENV_LEGACY = "DOTAGENTS_CMDS_PATH"
+
+#: The configurable user-scope store (D58). Discovery resolves the user scope's
+#: cmds dir through this, not a hardcoded ~/.agents, when set. This is the same
+#: var `dotagents env` emits (D79).
+AGENTS_DIR_ENV = "AGENTS_HOME"
+#: back-compat: DOTAGENTS_AGENTS_DIR is deprecated, removable next release.
+AGENTS_DIR_ENV_LEGACY = "DOTAGENTS_AGENTS_DIR"
+
+
+class Dotagents(LoggingArgs, Cli):
+    """Umbrella CLI for installing and building the dotagents config."""
+
+    _version_ = __version__
+    # Built-ins are handed to `duho.app` via `commands=` (see `main`/`_discover`),
+    # NOT resolved from `_subcommands_`: `app` returns the `commands=` list as-is
+    # and does not merge `_subcommands_` on top of it, so keeping the built-ins
+    # here too would double-register them. `_discover` is the single source.
+    _subcommands_ = []
+
+    #: Extra command search path(s), additive to the scope walk + env var.
+    #: `duho.parse_globals(Dotagents, argv)` reads this before the full parser is
+    #: built so `_discover` can honor it (an extra `--cmdspath` search path).
+    cmdspath: "list[str]" = []
+    "Extra directory to discover command modules from (repeatable)."
+    ("--cmdspath",)
+
+    def __call__(self) -> int:
+        self._logger_.info(
+            "pick a subcommand, e.g. `init`, `overlays`, `context`, `env`, "
+            "`build-pyz`"
+        )
+        return 0
+
+
+def _bundled_cmds_dir() -> "Path | None":
+    """The bundled command-module dir shipped inside the package (D76).
+
+    `<package>/_overlay/dotagents/cmds` is that dir. dotagents bundles no command
+    module of its own since D85 (link/sync moved to the private-sync overlay), so
+    it normally holds only its README -- but it stays a discovery source, and
+    `init` still lays it down as the user's drop-in point. Resolved `.pyz`-safe
+    via `_package_data_dir`, which
+    extracts a zip-backed `_overlay` to a real temp dir once -- so the modules
+    `discover_commands` imports from here always have a real on-disk `__file__`,
+    and the zipapp AST-introspection shim (`_repoint_zipapp_sources`) does NOT
+    need to cover them. Returns None if the package bundles no cmds dir."""
+    base = _package_data_dir("_overlay")
+    if base is None:
+        return None
+    cmds = base / "dotagents" / "cmds"
+    return cmds if cmds.is_dir() else None
+
+
+def _discover_dir(source, by_name: dict) -> None:
+    """Discover command modules from one directory source, resiliently.
+
+    A missing / unreadable / non-command source is skipped with a warning, never
+    fatal -- mirroring `duho.discover_commands`'s own per-command resilience.
+    Each discovered command is keyed by its
+    resolved subcommand name (`_parsername_` / class name), so a LATER source
+    overrides an earlier same-named command (built-in < bundled < scope < env <
+    flag)."""
+    from duho.discovery import discover_commands
+
+    path = Path(source)
+    if not path.is_dir():
+        return
+    try:
+        commands = discover_commands(path)
+    except (ImportError, NotImplementedError, OSError) as exc:
+        _LOGGER.warning("skipping command source %r: %s", str(source), exc)
+        return
+    for command in commands:
+        name = getattr(command, "_parsername_", None) or getattr(
+            command, "__name__", None
+        )
+        if name:
+            by_name[name] = command  # later source wins
+
+
+def _cmds_dirs() -> "list[Path]":
+    """Every `cmds` dir to discover command modules from, in Contract-A order.
+
+    Resolved with the SAME `get_file_paths` walk that backs `bin`/PATH discovery
+    (`_env.get_bin_paths`) -- one resolver call yields the cmds dir at EVERY level
+    in precedence order, so command discovery, PATH, and every other Contract-A
+    seam agree on which roots exist and in what order. NOT a hand-rolled loop over
+    installed overlays.
+
+    The per-level name-dict maps overlay levels to `<overlay-root>/cmds` and every
+    other level (system/user/project) to `<agents_root>/dotagents/cmds` (the
+    `Scope.cmds_dir` layout, D76). `get_file_paths` returns them in Contract-A
+    precedence: overlays first, then system, user, project. Discovery layers later
+    sources over earlier ones (see `_discover_dir`), so a project cmd overrides a
+    user cmd overrides an overlay cmd of the same name -- the intended precedence
+    (an overlay may SHIP a command; a user/project can still override it).
+
+    The store location is configurable (D58/D79): the user scope resolves through
+    `$AGENTS_HOME` (default `~/.agents`); the project scope is `<cwd>/.agents`.
+    `include_missing=True` (precursor semantics): every level's cmds dir is offered
+    and the caller's `_discover_dir` skips the ones that don't exist."""
+    from dotagents import _resolve, _scope
+
+    agents_dir = (
+        os.environ.get(AGENTS_DIR_ENV)
+        or os.environ.get(AGENTS_DIR_ENV_LEGACY)
+        or None
+    )
+    user = _scope.resolve_scope(global_scope=True, agents_dir=agents_dir)
+    resolved = _resolve.get_file_paths(
+        {"default": "dotagents/cmds", "overlay": "cmds"},
+        agents_dir=user.agents_root,
+        project_root=_scope.project_root_default(),
+        global_scope=False,
+        include_missing=True,
+    )
+    return [path for _level, path, _root in resolved]
+
+
+def _discover(argv=None) -> "list":
+    """Resolve the full command set: built-ins, then discovered modules.
+
+    Sources, earliest-to-latest (a later source overrides a same-named command,
+    dedup by resolved subcommand name):
+
+    1. the compiled built-in command classes (`_BUILTIN_COMMANDS`);
+    2. the bundled command-module dir `<package>/_overlay/dotagents/cmds` --
+       always available, even before an install (empty of commands since D85);
+    3. the Contract-A `cmds` dirs (`_cmds_dirs`): each installed overlay's
+       `<overlay-root>/cmds`, then system/user/project `<scope>/dotagents/cmds`,
+       in Contract-A precedence (overlays < system < user < project). This is what
+       lets an installed overlay SHIP a command, or a user drop a personal command
+       module into their private `<scope>/dotagents/cmds` (e.g. `leak-check`), while
+       a user/project cmd still overrides a same-named overlay cmd;
+    4. `$AGENTS_CMDS_PATH` entries (os.pathsep-split);
+    5. `--cmdspath` entries, read via `duho.parse_globals` before the full parser.
+
+    Every directory source is resilient: a missing / bad one is skipped with a
+    warning, never fatal.
+    """
+    by_name: "dict[str, object]" = {}
+
+    # 1. built-ins (lowest precedence)
+    for command in _BUILTIN_COMMANDS:
+        name = getattr(command, "_parsername_", None) or command.__name__
+        by_name[name] = command
+
+    # 2. bundled cmds dir (ships no command of its own since D85)
+    bundled = _bundled_cmds_dir()
+    if bundled is not None:
+        _discover_dir(bundled, by_name)
+
+    # 3. Contract-A cmds dirs: overlay cmds + scope (user/project) cmds, in
+    #    precedence order (overlays first, project last -> project wins).
+    for cmds_dir in _cmds_dirs():
+        _discover_dir(cmds_dir, by_name)
+
+    # 4. $AGENTS_CMDS_PATH (back-compat: $DOTAGENTS_CMDS_PATH, removable next release)
+    raw = os.environ.get(CMDS_PATH_ENV) or os.environ.get(CMDS_PATH_ENV_LEGACY)
+    if raw:
+        for entry in raw.split(os.pathsep):
+            if entry:
+                _discover_dir(entry, by_name)
+
+    # 5. --cmdspath (read the global before the full subcommand parser is built)
+    try:
+        globals_ = duho.parse_globals(Dotagents, argv)
+        for entry in getattr(globals_, "cmdspath", None) or []:
+            if entry:
+                _discover_dir(entry, by_name)
+    except Exception as exc:  # pragma: no cover - parse_globals is best-effort
+        _LOGGER.warning("could not read --cmdspath globals: %s", exc)
+
+    return list(by_name.values())
+
+
+def _repoint_zipapp_sources() -> None:
+    """Make duho's AST field-introspection work when running from a zipapp.
+
+    duho discovers each command's flags + help by parsing its module source
+    (`_introspect.getclsdef` -> `Path(module.__file__).read_text()`). Inside a
+    `.pyz` the module `__file__` is a zip-internal path `read_text()` can't open,
+    and duho catches that `OSError` *before* its `inspect.getsource` fallback --
+    so every field silently loses its declared flags and help (the positional
+    `path` degrades to `--path`, `--from` to `--from-`, help text vanishes).
+    Extract the affected module sources to real temp files and repoint `__file__`
+    so the read succeeds. A no-op for a plain install, where `__file__` already
+    exists on disk.
+
+    Each BUILT-IN command class lives in its own `dotagents.cli.<x>` module, so
+    EVERY such module is repointed (plus duho's `LoggingArgs` preset,
+    `duho.presets`). DISCOVERED command modules do NOT need repointing: an
+    overlay's or a scope's cmds live on the real filesystem, and for the bundled
+    `_overlay/dotagents/cmds` dir `_package_data_dir` extracts a zip-backed
+    `_overlay` to real temp files before `discover_commands` imports from it, so
+    their `__file__` already exists on disk.
+
+    Tracked upstream: jose-pr/duho#1 -- drop this shim (and the build-pyz CI
+    guard) once duho's getclsdef falls through to inspect.getsource when
+    _module_index raises."""
+    import importlib.resources as _ir
+
+    for modname in _COMMAND_MODULES + ("duho.presets",):
+        mod = sys.modules.get(modname)
+        if mod is None:
+            continue
+        current = getattr(mod, "__file__", None)
+        if current and Path(current).exists():
+            continue  # plain install: source already readable
+        top, _sep, rest = modname.partition(".")
+        rel = (rest.replace(".", "/") or "__init__") + ".py"
+        try:
+            resource = _ir.files(top).joinpath(rel)
+            if not resource.is_file():
+                continue
+            text = resource.read_text(encoding="utf-8")
+        except (FileNotFoundError, ModuleNotFoundError, OSError, TypeError):
+            continue
+        tmp = Path(tempfile.mkdtemp(prefix="dotagents-src-")) / (
+            modname.replace(".", "_") + ".py"
+        )
+        tmp.write_text(text, encoding="utf-8")
+        mod.__file__ = str(tmp)
+
+
+def main(argv=None) -> int:
+    _repoint_zipapp_sources()
+    # `duho.app` (not `duho.main`) so command discovery runs. Default dispatch:
+    # dotagents has no fan-out, so `app` calls each command's `__call__` exactly
+    # as `duho.main` did. `commands=` is the resolved built-ins + discovered set.
+    return duho.app(
+        Dotagents,
+        commands=_discover(argv),
+        argv=argv,
+        name="dotagents",
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dotagents/cli/_common.py

@@ -0,0 +1,331 @@
+"""Shared CLI-only helpers used across the per-command modules.
+
+Pure helpers with no dependency on the command classes or the umbrella, so
+command modules can import from here without creating an import cycle
+(`cli/__init__.py` imports the command modules, not the reverse). The public
+names `_compose_block` and `_package_data_dir` are re-exported from
+`dotagents.cli` (see `cli/__init__.py`) because other package modules import
+them as `dotagents.cli._compose_block` / `dotagents.cli._package_data_dir`.
+"""
+
+import importlib.resources
+import os
+import re
+import shutil
+import tempfile
+from pathlib import Path
+
+
+_extracted_dirs_cache: "dict[str, Path]" = {}
+
+
+# NOTE: `_resolve_required_tool` was removed. It existed so a compiled `audit` /
+# `leak-check` wrapper could locate a standalone script under `tools/`. Neither
+# wrapper exists now: `audit` is CI tooling for THIS repo (`tools/audit.py`, not a
+# dotagents command, not shipped), and `leak-check` is a personal command module in
+# the user's private `.agents/`. Nothing in the package shells out to `tools/`.
+
+
+def _package_data_dir(name: str) -> "Path | None":
+    """Resolve a directory under the installed `dotagents` package (e.g.
+    `_overlay` or `_payload`) to a real filesystem Path, working whether the
+    package is a plain directory (pip install / editable) or inside a zipapp.
+
+    Inside a zipapp, `importlib.resources.files()` returns a `zipfile.Path`
+    (a `Traversable`, not a real filesystem `Path`): `.is_dir()` correctly
+    reports membership in the archive, but `str(traversable)` produces a
+    path string that does not exist on disk (`Path(str(...)).exists()` is
+    always False -- there is no real file there to stat). So a zip-backed
+    hit is extracted once to a process-lifetime temp directory and that
+    real path is cached and returned; a plain-directory hit is returned
+    as-is. Returns None if the directory isn't present in the package at all.
+    """
+    if name in _extracted_dirs_cache:
+        return _extracted_dirs_cache[name]
+
+    traversable = importlib.resources.files("dotagents") / name
+    if not traversable.is_dir():
+        return None
+
+    as_path = Path(str(traversable))
+    if as_path.exists():
+        _extracted_dirs_cache[name] = as_path
+        return as_path
+
+    # Zip-backed (or otherwise non-filesystem) Traversable: extract to a
+    # temp dir that lives for the process lifetime.
+    extract_root = Path(tempfile.mkdtemp(prefix="dotagents-%s-" % name))
+
+    def _extract(node, dest: Path):
+        dest.mkdir(parents=True, exist_ok=True)
+        for child in node.iterdir():
+            child_dest = dest / child.name
+            if child.is_dir():
+                _extract(child, child_dest)
+            else:
+                child_dest.write_bytes(child.read_bytes())
+
+    _extract(traversable, extract_root)
+    _extracted_dirs_cache[name] = extract_root
+    return extract_root
+
+
+# The base overlay (neutral minimum) is bundled package data at
+# `src/dotagents/_overlay`; `init` and `install` both lay it down. Overlays
+# beyond the base are opt-in examples applied from an external path via
+# `install --overlays <dir>` (the installer bundles none of them).
+BASE_ROOT = _package_data_dir("_overlay") or (
+    Path(__file__).resolve().parent.parent / "_overlay"
+)
+
+# Base files that are create-if-absent only (never overwrite), i.e. everything
+# except the managed-block files (AGENTS.md/CLAUDE.md).
+BASE_PLAIN_FILES = [
+    "README.md",
+    "dotagents/DECISIONS.md",
+]
+
+
+def _compose_block(base_text: str, overlays: "list[Path]", logger) -> str:
+    """Fold each overlay's `rules`/`routing` contributions into the base block.
+
+    Rules append to "Always-on rules" and routing to "Load on demand", after the
+    base's own -- the base carries the mechanism (D57) and should read first. The
+    overlays fold in **`(priority, name)` order** (plan 02 / D68), NOT the caller's
+    list order: lower `priority` (default `DEFAULT_PRIORITY`, 500) sorts earlier, so
+    a numerically higher-priority overlay lands *last* and wins on conflict -- the
+    same "lower sorts earlier / higher wins" convention `_context.py` uses. `name`
+    is the tiebreaker, so equal-priority overlays produce a stable, deterministic
+    block regardless of add-invocation or discovery order. Returns `base_text`
+    unchanged when nothing contributes, so `init` (which takes no overlays) is
+    completely unaffected."""
+    from dotagents._overlays import read_manifest, rule_blocks, sort_overlays_by_priority
+
+    rules: "list[str]" = []
+    routing: "list[str]" = []
+    for overlay_dir in sort_overlays_by_priority(overlays):
+        manifest = read_manifest(overlay_dir)
+        blocks, warnings = rule_blocks(overlay_dir, manifest["rules"])  # type: ignore[arg-type]
+        for warning in warnings:
+            logger.warning("overlay %s: %s", manifest["name"], warning)
+        rules.extend(blocks)
+        routing.extend(manifest["routing"])  # type: ignore[arg-type]
+
+    if not rules and not routing:
+        return base_text
+
+    text = base_text
+    if rules:
+        # Append after the last always-on bullet, i.e. just before the next heading.
+        m = re.search(r"(?m)^## Load on demand", text)
+        if m is None:
+            logger.warning("base AGENTS.md has no 'Load on demand' heading; "
+                           "appending overlay rules at the end of the block")
+        else:
+            text = text[: m.start()] + "\n".join(rules) + "\n\n" + text[m.start():]
+    if routing:
+        # The base's placeholder sentence only makes sense with no routing lines.
+        text = re.sub(
+            r"(?m)^Nothing ships here by default[^\n]*\n(?:[^\n#<][^\n]*\n)*",
+            "",
+            text,
+        )
+        end = re.search(r"(?m)^<!-- dotagents:end -->", text)
+        insert_at = end.start() if end else len(text)
+        text = text[:insert_at] + "\n".join(routing) + "\n" + text[insert_at:]
+    return text
+
+
+def _installed_overlay_dirs(scope, source, *, adding=None, dry_run=False) -> "list[Path]":
+    """The overlay dirs to recompose the managed block over (plan 02 / D68).
+
+    Every overlay installed in `scope` contributes to the block, so the recompose is
+    a pure function of *which* overlays are present -- not of add-invocation order.
+    Each installed overlay ships its own `overlay.toml` + rules files (see
+    `install_overlay_dir`), so the installed dir is self-describing and used directly.
+
+    `adding` is the names being added/synced this call; on a `--dry-run` `add` they
+    are not yet on disk in the scope, so their **source** dir stands in so the dry-run
+    preview reflects what a real run would produce. A real (non-dry-run) run reads them
+    from the scope like any other installed overlay. Order here is irrelevant --
+    `_compose_block` sorts by `(priority, name)`.
+    """
+    from dotagents import _scope
+
+    adding = list(adding or [])
+    installed = set(_scope.discover_overlays(scope))
+    names = sorted(installed | set(adding))
+    dirs: "list[Path]" = []
+    for name in names:
+        if dry_run and name in adding and name not in installed:
+            # Not on disk yet (dry-run add): describe it from the source instead.
+            try:
+                dirs.append(source.overlay_dir(name))
+            except SystemExit:
+                pass
+        else:
+            dirs.append(scope.overlay_dir(name))
+    return dirs
+
+
+def _resolved_env(dest: Path, logger, agent_name: str) -> "dict[str, str]":
+    """The env CHANGES dotagents contributes, for agents that need a static
+    snapshot rather than a per-session hook.
+
+    `agent_name` is passed as `explicit` so the identity vars describe the agent the
+    file is FOR, not whichever harness happens to be running `init` -- a snapshot
+    written from Claude must still say `AGENT=codex` inside Codex's own config.
+
+    Assembling this executes overlay `env.py` files, so a broken overlay must not
+    take `init` down with it -- failure degrades to an empty set with a warning.
+    """
+    from dotagents import _env, _scope
+
+    try:
+        return _env.get_environment(
+            agents_dir=Path(dest),
+            project_root=_scope.project_root_default(),
+            base_env=dict(os.environ),
+            explicit=agent_name,
+            logger=logger,
+        )
+    except Exception as exc:  # noqa: BLE001 -- never let one overlay break init
+        logger.warning("could not assemble env for the static env block: %s", exc)
+        return {}
+
+
+def _apply_base(
+    src: Path, dest: Path, force: bool, dry_run: bool, logger,
+    agents: "list[str] | None" = None,
+    wire_hooks: bool = False,
+) -> None:
+    """Lay down the base overlay: managed-block merge AGENTS.md/CLAUDE.md,
+    create-if-absent the plain files. Shared by `init` and `install`.
+
+    With `wire_hooks`, each active agent also gets its hooks merged and the shared
+    skills dir linked into its config dir (a no-op for adapters that don't
+    implement it). Done here because this is where the active-agent list is
+    already resolved."""
+    from dotagents import _agents
+    import os
+
+    base_agents = (Path(src) / "AGENTS.md").read_text(encoding="utf-8")
+
+    # True only when the caller named agents with `--agents`. Writes that touch an
+    # agent's own main config file are gated on this, so merely *running* under a
+    # harness never rewrites its config behind the user's back.
+    explicitly_requested = bool(agents)
+
+    active_agents = []
+    if agents:
+        for name in agents:
+            agent = _agents.get_agent(name)
+            if agent:
+                active_agents.append(agent)
+            else:
+                logger.warning(f"Unknown agent: {name}")
+    else:
+        # Default: all detected + claude
+        all_agents = _agents.get_all_agents()
+        active_agents = [a for a in all_agents if a.detect_env(os.environ)]
+        if not any(a.name == "claude" for a in active_agents):
+            active_agents.append(_agents.ClaudeAgent())
+
+    for agent in active_agents:
+        agent.write_base_config(
+            dest, src, base_agents, force=force, dry_run=dry_run, logger=logger
+        )
+        if wire_hooks:
+            agent.wire_hooks(dest, dry_run=dry_run, logger=logger)
+            # Agents with no per-session env mechanism (Codex) take a static
+            # snapshot of the resolved env instead. Only ever on an EXPLICIT
+            # `--agents <name>`: this edits the user's main config file with values
+            # that go stale, so it must be asked for, never triggered by
+            # auto-detection. Resolved lazily -- assembling it runs overlay `env.py`.
+            if explicitly_requested and hasattr(agent, "write_env_block"):
+                agent.write_env_block(
+                    _resolved_env(dest, logger, agent.name),
+                    dry_run=dry_run,
+                    logger=logger,
+                )
+
+    for rel in BASE_PLAIN_FILES:
+        source_path = Path(src) / rel
+        if not source_path.exists():
+            continue
+        target_path = dest / rel
+        if target_path.exists():
+            logger.info("skipped (present): %s", rel)
+            continue
+        logger.info("created: %s", rel)
+        if not dry_run:
+            target_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(str(source_path), str(target_path))
+
+    # Create `<dest>/dotagents/cmds/` and lay down whatever the base overlay
+    # bundles for it. dotagents itself now bundles NO command module (D85:
+    # link/sync moved to the private-sync overlay as link-project/sync-project,
+    # with their logic) -- but the DIR is still created unconditionally, because
+    # it is the documented user extension point: a `*.py` command module dropped
+    # here is discovered with zero config (see the README laid down beside it).
+    # Create-if-absent per file, exactly like the plain files -- a user's own
+    # edits to an installed command module are never clobbered on a reinstall.
+    cmds_src = Path(src) / "dotagents" / "cmds"
+    cmds_dest = dest / "dotagents" / "cmds"
+    if not dry_run:
+        cmds_dest.mkdir(parents=True, exist_ok=True)
+    if cmds_src.is_dir():
+        sources = sorted(cmds_src.glob("*.py")) + sorted(cmds_src.glob("*.md"))
+        for source_path in sources:
+            if source_path.name.startswith("_"):
+                continue
+            rel = "dotagents/cmds/%s" % source_path.name
+            target_path = cmds_dest / source_path.name
+            if target_path.exists():
+                logger.info("skipped (present): %s", rel)
+                continue
+            logger.info("created: %s", rel)
+            if not dry_run:
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(str(source_path), str(target_path))
+
+
+def _resolve_from(from_arg: "str | None", default: Path) -> Path:
+    """Resolve --from to a local directory Path. A bare local path/dir is used
+    directly; a URI string is constructed via pathlib_next's UriPath (lazy
+    import so the `uri` extra is only required when actually used)."""
+    if from_arg is None:
+        return default
+    candidate = Path(from_arg)
+    if candidate.exists():
+        return candidate
+    if "://" in from_arg or from_arg.startswith(("http:", "https:", "sftp:", "s3:", "zip:")):
+        try:
+            from pathlib_next import UriPath
+        except ImportError as e:
+            raise SystemExit(
+                'error: --from %r needs URI support. Install it with: pip install "dotagents-cli[uri]"'
+                % from_arg
+            ) from e
+        return UriPath(from_arg)
+    raise SystemExit("error: --from path does not exist: %s" % from_arg)
+
+
+def _run_overlay_setup(dest_dir, name, *, scope, no_setup, dry_run, logger):
+    """Run an installed overlay's `setup` script, honoring `--no-setup`.
+
+    Thin wrapper over `_overlays.run_overlay_setup` that resolves the store path
+    from the scope (D58 configurable store, passed as `AGENTS_HOME`) and
+    short-circuits when `--no-setup` is given or the overlay ships no script.
+    Returns the setup exit code (0 when skipped / absent), so a non-zero result
+    surfaces as a clear error rather than a silent skip."""
+    from dotagents import _overlays
+
+    if no_setup:
+        if _overlays.find_setup_script(dest_dir) is not None:
+            logger.info("skipping setup for %s (--no-setup)", name)
+        return 0
+    rc = _overlays.run_overlay_setup(
+        dest_dir, name, agents_dir=scope.agents_root, dry_run=dry_run, logger=logger,
+    )
+    return rc or 0