dotagents-cli 0.3.0__py3-none-any.whl

dotagents/cli/build_pyz.py

@@ -0,0 +1,107 @@
+"""`dotagents build-pyz` -- vendor deps and package a self-contained pyz."""
+
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+from duho import Cmd, LoggingArgs
+
+
+class BuildPyz(LoggingArgs, Cmd):
+    """Vendor duho/pathlib_next via pip --target and package a self-contained dotagents.pyz."""
+
+    _parsername_ = "build-pyz"
+
+    out: Path = Path("dist") / "dotagents.pyz"
+    "Output path for the built pyz."
+    ("--out",)
+
+    python: str = "/usr/bin/env python3"
+    "Shebang line to embed in the pyz."
+    ("--python",)
+
+    duho_version: str = "0.4.0"
+    "Pinned duho version to vendor."
+    ("--duho-version",)
+
+    pathlib_next_version: str = "0.8.0"
+    "Pinned pathlib_next version to vendor."
+    ("--pathlib-next-version",)
+
+    tools_dir: Optional[Path] = None
+    "Repo tools/ dir (required tooling) to bundle as _tools (default: autodetected)."
+    ("--tools-dir",)
+
+    def __call__(self) -> int:
+        import zipapp
+
+        # This module lives at src/dotagents/cli/build_pyz.py, so the repo root
+        # is parents[3] (cli -> dotagents -> src -> repo) and the dotagents
+        # package dir is parents[1].
+        repo_root = Path(__file__).resolve().parents[3]
+        tools_src = Path(self.tools_dir) if self.tools_dir else (repo_root / "tools")
+        if not tools_src.exists():
+            raise SystemExit("error: repo tools/ not found at %s (pass --tools-dir)" % tools_src)
+
+        with tempfile.TemporaryDirectory(prefix="dotagents-pyz-") as tmp:
+            stage = Path(tmp) / "stage"
+            stage.mkdir()
+
+            self._logger_.info(
+                "vendoring duho==%s pathlib_next==%s via pip --target",
+                self.duho_version,
+                self.pathlib_next_version,
+            )
+            rc = subprocess.call(
+                [
+                    sys.executable,
+                    "-m",
+                    "pip",
+                    "install",
+                    "--target",
+                    str(stage),
+                    "duho==%s" % self.duho_version,
+                    "pathlib_next==%s" % self.pathlib_next_version,
+                ]
+            )
+            if rc != 0:
+                return rc
+
+            dotagents_pkg_src = Path(__file__).resolve().parents[1]
+            dotagents_pkg_dest = stage / "dotagents"
+            shutil.copytree(
+                dotagents_pkg_src,
+                dotagents_pkg_dest,
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+            )
+
+            tools_dest = dotagents_pkg_dest / "_tools"
+            shutil.copytree(
+                tools_src,
+                tools_dest,
+                ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+            )
+
+            for path in stage.rglob("*.dist-info"):
+                shutil.rmtree(path, ignore_errors=True)
+            for path in stage.rglob("__pycache__"):
+                shutil.rmtree(path, ignore_errors=True)
+            for path in stage.rglob("tests"):
+                if path.is_dir():
+                    shutil.rmtree(path, ignore_errors=True)
+
+            main_py = stage / "__main__.py"
+            main_py.write_text(
+                "from dotagents.cli import main\n\nraise SystemExit(main())\n",
+                encoding="utf-8",
+            )
+
+            out_path = Path(self.out)
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+            zipapp.create_archive(str(stage), target=str(out_path), interpreter=self.python)
+            self._logger_.info("built %s", out_path)
+
+        return 0

dotagents/cli/context.py

@@ -0,0 +1,129 @@
+"""`dotagents context` -- assemble the effective context for agents (Plan 04)."""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from duho import Cmd, LoggingArgs
+
+
+def _write_stdout(text: str) -> None:
+    """Write to stdout as UTF-8, whatever the console's encoding claims to be.
+
+    A bare `print()` encodes with the console codepage -- cp1252 on a default
+    Windows shell -- so a single character outside Latin-1 (an arrow, a box-drawing
+    rule, a curly quote, any emoji) raises UnicodeEncodeError and the command dies
+    having emitted nothing. Context files routinely contain such characters, and
+    this is the SessionStart hook's payload, so the failure is both likely and
+    silent. Write bytes through the underlying buffer instead, replacing anything
+    even UTF-8 cannot represent rather than aborting.
+    """
+    data = text.encode("utf-8", errors="replace")
+    buffer = getattr(sys.stdout, "buffer", None)
+    if buffer is None:  # pragma: no cover -- captured/replaced stdout in tests
+        sys.stdout.write(text)
+        return
+    buffer.write(data)
+    buffer.flush()
+
+
+class Context(LoggingArgs, Cmd):
+    """Assemble the effective context for agents (Plan 04)."""
+
+    _parsername_ = "context"
+
+    format: str = "markdown"
+    "Output format: markdown, system-reminder, or json."
+    ("--format",)
+
+    global_scope: bool = False
+    "Use global scope."
+    ("--global", "-g")
+
+    agents: "list[str]" = []
+    "List of agents to generate context for (e.g. claude,gemini). Default: active agent."
+    ("--agents",)
+
+    out: str = "-"
+    "Output path (positional). Default '-' = stdout; a path writes that file; use "
+    "--write-agent to write each agent's native config file instead."
+    ("out",)
+
+    write_agent: bool = False
+    "Write each agent's native config file (e.g. Claude's CONTEXT.md) instead of a path."
+    ("--write-agent",)
+
+    def __call__(self) -> int:
+        from dotagents import _agents
+        from dotagents import _context
+        import json
+        import os
+
+        project_root = Path.cwd()
+        agents_dir = Path.home() / ".agents"
+
+        agent_names = []
+        if self.agents:
+            for a in self.agents:
+                agent_names.extend([x.strip() for x in a.split(",") if x.strip()])
+
+        if agent_names:
+            active_agents = []
+            for name in agent_names:
+                a = _agents.get_agent(name)
+                if a:
+                    active_agents.append(a)
+                else:
+                    self._logger_.warning("Unknown agent: %s", name)
+        else:
+            # Default target = the active agent (env-var detection / $AGENTS_HARNESS
+            # stamp / config-file detect), not "all detected".
+            active_agents = [
+                _agents.resolve_active_agent(os.environ, root=project_root)
+            ]
+
+        # --- JSON: emit structured data (object for one agent, array for many);
+        #     never writes native config files. ---
+        if self.format == "json":
+            payloads = [
+                _context.assemble_context_data(
+                    agent, agents_dir, project_root, global_scope=self.global_scope
+                )
+                for agent in active_agents
+            ]
+            out_obj = payloads[0] if len(payloads) == 1 else payloads
+            blob = json.dumps(out_obj, indent=2, ensure_ascii=False)
+            if self.out and self.out != "-":
+                Path(self.out).write_text(blob, encoding="utf-8")
+                self._logger_.info("Wrote JSON context to %s", self.out)
+            else:
+                print(blob)  # default '-' -> stdout (json never writes native configs)
+            return 0
+
+        # --- markdown / system-reminder text paths ---
+        for agent in active_agents:
+            text = _context.assemble_context(
+                agent, agents_dir, project_root, global_scope=self.global_scope
+            )
+
+            if self.format == "system-reminder":
+                text = (
+                    "<!-- system-reminder: begin -->\n"
+                    + text
+                    + "\n<!-- system-reminder: end -->"
+                )
+
+            if self.write_agent:
+                agent.write_context(agents_dir, text, force=False, dry_run=False, logger=self._logger_)
+            elif self.out == "-":
+                # Just the context on stdout. A per-agent delimiter is emitted ONLY when
+                # more than one agent is generated, so a single-agent run (the default)
+                # is clean, pipeable output with no decoration to strip.
+                if len(active_agents) > 1:
+                    _write_stdout("# --- %s ---\n" % agent.name)
+                _write_stdout(text + "\n")
+            else:
+                Path(self.out).write_text(text, encoding="utf-8")
+                self._logger_.info(f"Wrote {agent.name} context to {self.out}")
+
+        return 0

dotagents/cli/env.py

@@ -0,0 +1,168 @@
+"""`dotagents env` -- chained env-file assembly + env.py execution (plan 07).
+
+Self-contained block: all logic lives in `_env.py` (frozen contract B) and
+`_agents.stamp_identity` (plan 08). The only umbrella touch is registering
+`Env` on `Dotagents._subcommands_` (in `cli/__init__.py`). Never logs
+DOTAGENTS_*/AGENTS_* VALUES -- output goes to stdout for the caller to consume;
+the logger only ever names vars (Leakage rule).
+"""
+
+from pathlib import Path
+
+from duho import Cmd, LoggingArgs
+
+
+def _dotenv_value(v: str) -> str:
+    """Dotenv quoting: bare unless the value needs quoting.
+
+    A value with whitespace, ``#``, ``"`` or a newline is wrapped in double
+    quotes with ``"``, ``\\`` and newline backslash-escaped; otherwise emitted
+    bare (the ``.env`` / ``docker --env-file`` convention).
+    """
+    if v == "":
+        return ""
+    if any(c in v for c in " \t#\"\n") or v.strip() != v:
+        esc = v.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+        return '"%s"' % esc
+    return v
+
+
+def _format_env(env: "dict[str, str]", output_format: str) -> str:
+    """Render the assembled env in the requested (canonical or aliased) format.
+
+    Shell-sourceable / assignment forms, one var per line:
+
+    * ``export`` (aliases ``posix``/``sh``/``bash``) -- ``export KEY="value"``,
+      value JSON-quoted; the POSIX default a SessionStart hook sources.
+    * ``dotenv`` (alias ``env``) -- bare ``KEY=value`` (no ``export``), value
+      quoted only when it contains whitespace/``#``/``"``/newline (``.env`` /
+      ``docker --env-file`` rules). Distinct from ``export``: assigns, doesn't
+      source+export.
+    * ``powershell`` (aliases ``pwsh``/``ps``) -- ``$env:KEY = 'value'``,
+      single-quoted, ``'`` escaped as ``''``.
+    * ``cmd`` (aliases ``bat``/``batch``) -- ``set "KEY=value"``. cmd has NO way
+      to escape a literal ``"`` inside a value; any ``"`` is emitted as ``""``
+      best-effort (documented limitation).
+    * ``fish`` -- ``set -gx KEY value``, single-quoted, ``'`` escaped as ``\\'``.
+
+    Data forms:
+
+    * ``json`` -- a sorted JSON object.
+    * ``ini``  -- ``KEY=value`` lines under a ``[env]`` section.
+    * ``yaml`` -- ``KEY: value`` lines (values quoted when ambiguous).
+
+    Aliases are normalized here via :data:`dotagents._env.FORMAT_ALIASES`. Values
+    are emitted verbatim (this is the point of the command); callers must treat
+    the output as sensitive.
+    """
+    import json as _json
+
+    from dotagents._env import FORMAT_ALIASES
+
+    fmt = FORMAT_ALIASES.get(output_format, output_format)
+    keys = sorted(env)
+
+    if fmt == "json":
+        return _json.dumps({k: env[k] for k in keys}, indent=2, sort_keys=True)
+    if fmt == "ini":
+        return "\n".join(["[env]"] + ["%s=%s" % (k, env[k]) for k in keys])
+    if fmt == "yaml":
+        lines = []
+        for k in keys:
+            v = env[k]
+            if v == "" or any(c in v for c in ":#'\"\n") or v.strip() != v:
+                v = _json.dumps(v)
+            lines.append("%s: %s" % (k, v))
+        return "\n".join(lines)
+    if fmt == "dotenv":
+        return "\n".join("%s=%s" % (k, _dotenv_value(env[k])) for k in keys)
+    if fmt == "powershell":
+        return "\n".join(
+            "$env:%s = '%s'" % (k, env[k].replace("'", "''")) for k in keys
+        )
+    if fmt == "cmd":
+        return "\n".join(
+            'set "%s=%s"' % (k, env[k].replace('"', '""')) for k in keys
+        )
+    if fmt == "fish":
+        return "\n".join(
+            "set -gx %s '%s'" % (k, env[k].replace("'", "\\'")) for k in keys
+        )
+    # default / "export"
+    return "\n".join("export %s=%s" % (k, _json.dumps(env[k])) for k in keys)
+
+
+class Env(LoggingArgs, Cmd):
+    """Assemble the chained env (env files + env.py execution) under contract B.
+
+    Prepends overlay/level ``bin`` dirs to ``PATH`` first, then evaluates the
+    ``pre.*`` tier and the main tier in precedence order (overlays -> user ->
+    project -> project-root), chaining each file over the accumulated env so
+    later files win. ``.py`` files are EXECUTED and emit JSON env changes; plain
+    files are sourced. Standardized ``AGENTS_*``/``AGENT`` identity vars and the
+    ``AGENTS_PROXY`` model are wired in.
+
+    ``--diff`` emits only the vars that differ from the current environment (what
+    a SessionStart hook injects); the default emits the full assembled env merged
+    over the current one. Output is sensitive -- it may carry secret values.
+
+    ``--format`` selects the emitted syntax and defaults to ``auto``, which
+    detects the CALLING shell (parent-process chain) and picks a matching format
+    so the output is sourceable where it runs: ``export`` (aliases
+    ``posix``/``sh``/``bash``), ``dotenv`` (``env``), ``powershell``
+    (``pwsh``/``ps``), ``cmd`` (``bat``/``batch``), ``fish``, plus the data
+    forms ``json``/``ini``/``yaml``. An explicit ``--format`` always wins."""
+
+    _parsername_ = "env"
+
+    format: str = "auto"
+    (
+        "Output format. Default 'auto' detects the calling shell. Shell forms: "
+        "export (aliases posix/sh/bash), dotenv (env), powershell (pwsh/ps), "
+        "cmd (bat/batch), fish. Data forms: json, ini, yaml."
+    )
+    ("--format",)
+
+    diff: bool = False
+    "Emit only vars that differ from the current environment."
+    ("--diff",)
+
+    global_scope: bool = False
+    "Use global scope (skip project-level env files)."
+    ("--global", "-g")
+
+    def __call__(self) -> int:
+        import os
+
+        from dotagents import _env
+
+        project_root = Path.cwd()
+        agents_dir = Path.home() / ".agents"
+        base = dict(os.environ)
+
+        if self.format not in _env.KNOWN_FORMATS:
+            raise SystemExit(
+                "error: --format must be one of %s (got %r)"
+                % (", ".join(_env.KNOWN_FORMATS), self.format)
+            )
+        # `auto` (the default) resolves to the calling shell's format; an explicit
+        # --format always wins. Detection reads process names only (never values).
+        output_format = self.format
+        if output_format == "auto":
+            output_format = _env.detect_shell_format()
+
+        if self.diff:
+            env = _env.get_diff(
+                agents_dir=agents_dir, project_root=project_root,
+                base_env=base, global_scope=self.global_scope, logger=self._logger_,
+            )
+        else:
+            changes = _env.get_environment(
+                agents_dir=agents_dir, project_root=project_root,
+                base_env=base, global_scope=self.global_scope, logger=self._logger_,
+            )
+            env = dict(base)
+            env.update(changes)
+
+        print(_format_env(env, output_format))
+        return 0

dotagents/cli/init.py

@@ -0,0 +1,117 @@
+"""`dotagents init` -- lay down the neutral base config (+ optional wrappers)."""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+from duho import Cmd, LoggingArgs
+
+from dotagents.cli._common import BASE_ROOT, _apply_base, _resolve_from
+
+
+class Init(LoggingArgs, Cmd):
+    """Lay down the neutral base config -- the `AGENTS.md` scaffolding and design-log
+    convention, never the opinionated overlays (those come from `overlays add`).
+
+    Scope: **project** by default (``<cwd>/.agents``), or the **user** store with
+    ``-g/--global`` (``~/.agents``). ``--dest`` overrides the resolved location.
+    ``--bin-dir`` additionally writes ``dotagents`` wrapper scripts there so the
+    command is on your PATH (only meaningful when running from a built ``.pyz``).
+    """
+
+    _parsername_ = "init"
+
+    global_scope: bool = False
+    "Init the user store (~/.agents) instead of this project's <cwd>/.agents."
+    ("--global", "-g")
+
+    agents_dir: Optional[Path] = None
+    "User store location for -g (default ~/.agents; configurable via $AGENTS_STORE_DIR)."
+    ("--agents-dir",)
+
+    dest: Optional[Path] = None
+    "Explicit destination, overriding the resolved scope (project/user)."
+    ("--dest",)
+
+    from_: Optional[str] = None
+    "Source directory/URI for the base overlay (default: bundled overlay)."
+    ("--from",)
+
+    bin_dir: Optional[Path] = None
+    "Also write dotagents/dotagents.cmd wrapper scripts here (puts the command on PATH)."
+    ("--bin-dir",)
+
+    dry_run: bool = False
+    "Show what would be written without touching anything."
+    ("--dry-run",)
+
+    force: bool = False
+    "Replace AGENTS.md/CLAUDE.md wholesale (with backup) instead of block-merging."
+    ("--force",)
+
+    agents: "list[str]" = []
+    "List of agents to install for (e.g. claude,gemini). Default: auto-detect + claude."
+    ("--agents",)
+
+    no_hooks: bool = False
+    "Skip wiring agent hooks and the shared skills link into the agent's config dir."
+    ("--no-hooks",)
+
+    def __call__(self) -> int:
+        src = _resolve_from(self.from_, BASE_ROOT)
+        if self.dest is not None:
+            dest = Path(self.dest).expanduser().resolve()
+        else:
+            from dotagents import _scope
+
+            scope = _scope.resolve_scope(self.global_scope, agents_dir=self.agents_dir)
+            dest = Path(scope.agents_root).expanduser().resolve()
+            self._logger_.info("scope: %s (%s)", scope.level, dest)
+
+        agent_names = []
+        if self.agents:
+            for a in self.agents:
+                agent_names.extend([x.strip() for x in a.split(",") if x.strip()])
+
+        _apply_base(
+            Path(src), dest, self.force, self.dry_run, self._logger_,
+            agents=agent_names if agent_names else None,
+            wire_hooks=not self.no_hooks,
+        )
+
+        if not self.dry_run:
+            from dotagents._wrappers import check_path_warning, write_wrappers
+
+            pyz_path = Path(sys.argv[0]).resolve()
+            if pyz_path.suffix != ".pyz":
+                # Running from a plain install (not a pyz): the wrappers point at
+                # `python -m dotagents` instead of a nonexistent pyz path.
+                pyz_path = None
+
+            # `<scope>/bin/` is always populated, with a path relative to the scope
+            # so the store stays relocatable. Everything downstream of `init` --
+            # the SessionStart hook, overlay `bin/` PATH entries, an overlay setup
+            # script calling a sibling -- shells out to `dotagents` by name, so a
+            # scope without it is a scope where those silently fail.
+            targets = [(dest / "bin", True)]
+            if self.bin_dir is not None:
+                targets.append((Path(self.bin_dir), False))
+
+            for bin_dir, relative in targets:
+                if pyz_path is not None:
+                    for w in write_wrappers(bin_dir, pyz_path, relative=relative):
+                        self._logger_.info("wrapper: %s", w)
+                else:
+                    self._logger_.info(
+                        "skipped wrapper install in %s: not running from a .pyz "
+                        "(use build-pyz first)", bin_dir,
+                    )
+
+            if self.bin_dir is not None:
+                warning = check_path_warning(Path(self.bin_dir))
+                if warning:
+                    self._logger_.warning(warning)
+
+        if self.dry_run:
+            self._logger_.info("dry-run: no files were written")
+        return 0