dotagents-cli 0.3.0__tar.gz → 0.3.1__tar.gz

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Fixed
+
+- fix: **`dotagents env --format export`/`dotenv`/`fish` now emit a POSIX PATH on
+  Windows**, instead of the OS-native `C:\...;C:\...` form. This is the exact
+  command the Claude `SessionStart` hook appends into `$CLAUDE_ENV_FILE`, which
+  Claude sources before *every* subsequent Bash tool call in the session — an
+  unconverted PATH broke command lookup (`git`, `grep`, `head`, `python`, ...) for
+  the rest of the session once poisoned, not just once. PATH-shaped values are
+  now converted per segment: backslash to forward-slash, `;` to `:`, and a drive
+  letter to its MSYS mount point (`C:/...` -> `/c/...` — required for PATH
+  *lookups* specifically; slash direction alone does not work in MSYS2/Cygwin
+  bash). `PATHEXT` is dropped (no POSIX meaning). A handful of real Windows env
+  vars with parentheses in their names (`ProgramFiles(x86)`) are also dropped for
+  these formats — `export FOO(X86)=...` is a bash syntax error, not a bad value,
+  and aborts sourcing the rest of the file. `powershell`/`cmd`/`json`/`ini`/`yaml`
+  are unaffected.
+- fix: a UNC PATH segment (`\\server\share\...`) no longer collapses to a single
+  leading slash (`/server/share/...`) during the POSIX conversion above — MSYS
+  requires the double-slash UNC root (`//server/share/...`) to resolve it.
+
+## [0.3.1] - 2026-07-24
+
+Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0).
+
 ## [0.3.0] - 2026-07-24
 
 ### Changed

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dotagents-cli
-Version: 0.3.0
+Version: 0.3.1
 Summary: The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents
 Project-URL: Homepage, https://github.com/jose-pr/dotagents/
 Project-URL: Repository, https://github.com/jose-pr/dotagents
@@ -62,6 +62,7 @@ Description-Content-Type: text/markdown
 # dotagents
 
 [![Test](https://img.shields.io/github/actions/workflow/status/jose-pr/dotagents/test.yml?branch=main&label=tests)](https://github.com/jose-pr/dotagents/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/dotagents-cli.svg)](https://pypi.org/project/dotagents-cli/)
 [![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://jose-pr.github.io/dotagents/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/dotagents/blob/main/LICENSE)
 
@@ -123,8 +124,13 @@ manifest read by the `dotagents overlays` subcommand, which manages overlays by
 
 ## Install
 
-**`dotagents init`** lays down the neutral base config; a self-contained downloadable
-`.pyz` needs no `pip install` at all.
+```bash
+pip install dotagents-cli   # gives you `import dotagents` and the `dotagents` command
+```
+
+Or skip `pip` entirely with the self-contained downloadable `.pyz` (see below).
+
+**`dotagents init`** lays down the neutral base config.
 
 `init` writes the `.agents/` scaffolding — the `AGENTS.md` managed block, the per-agent
 `<CLAUDE|ANTIGRAVITY|...>.md → @AGENTS.md` pattern, the design-log convention — and

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/README.md

@@ -1,6 +1,7 @@
 # dotagents
 
 [![Test](https://img.shields.io/github/actions/workflow/status/jose-pr/dotagents/test.yml?branch=main&label=tests)](https://github.com/jose-pr/dotagents/actions/workflows/test.yml)
+[![PyPI](https://img.shields.io/pypi/v/dotagents-cli.svg)](https://pypi.org/project/dotagents-cli/)
 [![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://jose-pr.github.io/dotagents/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/jose-pr/dotagents/blob/main/LICENSE)
 
@@ -62,8 +63,13 @@ manifest read by the `dotagents overlays` subcommand, which manages overlays by
 
 ## Install
 
-**`dotagents init`** lays down the neutral base config; a self-contained downloadable
-`.pyz` needs no `pip install` at all.
+```bash
+pip install dotagents-cli   # gives you `import dotagents` and the `dotagents` command
+```
+
+Or skip `pip` entirely with the self-contained downloadable `.pyz` (see below).
+
+**`dotagents init`** lays down the neutral base config.
 
 `init` writes the `.agents/` scaffolding — the `AGENTS.md` managed block, the per-agent
 `<CLAUDE|ANTIGRAVITY|...>.md → @AGENTS.md` pattern, the design-log convention — and

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "hatchling.build"
 # redirect/placeholder before someone else does, but the CLI ships under -cli.
 [project]
 name = "dotagents-cli"
-version = "0.3.0"
+version = "0.3.1"
 authors = [{ name = "Jose A." }]
 description = "The dotagents CLI: install and manage a portable ~/.agents config for AI coding agents"
 readme = "README.md"

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/src/dotagents/cli/env.py

@@ -7,10 +7,17 @@ DOTAGENTS_*/AGENTS_* VALUES -- output goes to stdout for the caller to consume;
 the logger only ever names vars (Leakage rule).
 """
 
-from pathlib import Path
+import re
+from pathlib import Path, PureWindowsPath
 
 from duho import Cmd, LoggingArgs
 
+# POSIX shell variable names: a leading letter/underscore, then letters/digits/
+# underscores only (IEEE Std 1003.1 "Name"). Windows env vars like
+# `ProgramFiles(x86)` don't qualify -- `(`/`)` make `export NAME=...` a syntax
+# error in bash, not just an unset/misinterpreted var.
+_POSIX_IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
 
 def _dotenv_value(v: str) -> str:
     """Dotenv quoting: bare unless the value needs quoting.
@@ -27,6 +34,75 @@ def _dotenv_value(v: str) -> str:
     return v
 
 
+def _looks_like_path_list(key: str, value: str) -> bool:
+    """True if `key`/`value` is a PATH-shaped var that needs POSIX conversion
+    for a shell-sourceable format.
+
+    Matches `PATH` exactly and any `*_PATH`/`*PATH` suffix an overlay's env.py
+    might emit (e.g. `PYTHONPATH`, `AGENTS_LIB_PATH`) -- the same convention
+    `get_bin_paths`/contract B use for path-list vars. Requires the value to
+    actually look like an OS-native path list (contains a backslash, or the
+    Windows `;` separator) so an ordinary single POSIX path or an unrelated
+    string is never touched.
+    """
+    if not key.endswith("PATH"):
+        return False
+    return "\\" in value or ";" in value
+
+
+_DRIVE_LETTER_RE = re.compile(r"^([A-Za-z]):/")
+
+
+def _to_posix_path(segment: str) -> str:
+    """One path segment, converted to a form MSYS2/Cygwin bash can actually
+    resolve a PATH lookup through -- not just cosmetically POSIX-shaped.
+
+    Uses ``PureWindowsPath`` explicitly, NOT the platform-dependent bare
+    ``Path``. This distinction is load-bearing, not stylistic: `Path` resolves
+    to `PosixPath` on a POSIX host, and `PosixPath("C:\\Users\\x").as_posix()`
+    does NOT recognize `C:` as a drive or `\\` as a separator -- backslashes
+    pass through as literal filename characters. This code runs in CI on
+    Linux/macOS runners (the test suite exercises it there), so a bare `Path`
+    silently only worked when the CI happened to run on a Windows runner --
+    which for THIS job it does not. `PureWindowsPath` parses Windows syntax
+    unconditionally, everywhere, matching what the value actually is (a
+    Windows path string), independent of the host running the code.
+
+    `PureWindowsPath(...).as_posix()` alone still leaves a drive letter as
+    `C:/...`, which fails PATH lookup identically to the backslash form --
+    verified directly on Windows (`command -v grep` empty for `C:/Program
+    Files/Git/usr/bin`, populated for `/c/Program Files/Git/usr/bin`, same
+    directory). So a genuine drive-letter prefix is additionally rewritten to
+    its MSYS mount point (`C:/...` -> `/c/...`).
+
+    A UNC segment (`\\\\server\\share\\...`) is handled correctly by
+    `PureWindowsPath` natively -- it already preserves the double-slash UNC
+    root through `.as_posix()` (`//server/share/...`), unlike a naive
+    backslash-replace on a plain string, which collapses it to one slash.
+
+    An already-POSIX or relative segment (`.agents/bin`, `/etc/agents/bin`) is
+    parsed as a relative Windows path (backslashes are still separators there,
+    but there are none to convert) and passes through unchanged.
+    """
+    posix = PureWindowsPath(segment).as_posix()
+    m = _DRIVE_LETTER_RE.match(posix)
+    if m:
+        return "/%s%s" % (m.group(1).lower(), posix[2:])
+    return posix
+
+
+def _to_posix_path_list(value: str) -> str:
+    """Convert an OS-native (Windows) `;`-joined path list to a POSIX
+    `:`-joined one, for a shell-sourceable target format.
+
+    Empty segments are dropped (a stray leading/trailing `;` must not become a
+    bare `:` -- POSIX treats an empty PATH segment as `.`, the cwd, which is
+    both wrong and a real security footgun).
+    """
+    segments = [_to_posix_path(s) for s in value.split(";") if s]
+    return ":".join(segments)
+
+
 def _format_env(env: "dict[str, str]", output_format: str) -> str:
     """Render the assembled env in the requested (canonical or aliased) format.
 
@@ -60,6 +136,37 @@ def _format_env(env: "dict[str, str]", output_format: str) -> str:
     from dotagents._env import FORMAT_ALIASES
 
     fmt = FORMAT_ALIASES.get(output_format, output_format)
+
+    # `get_environment` assembles PATH using the HOST OS's own convention
+    # (os.pathsep + native Path separators -- `;` and `\` on Windows), because
+    # that is what a Windows subprocess (cmd/PowerShell, or `dotagents` itself
+    # spawning a child) needs. Shell-sourceable POSIX formats need the opposite:
+    # bash/fish always use `:` and `/`, regardless of host OS. Left unconverted
+    # on Windows, `export PATH="C:\...;C:\..."` sourced into a POSIX shell (this
+    # is exactly what the SessionStart hook writes into $CLAUDE_ENV_FILE) hands
+    # bash a PATH it cannot parse -- every `;`-joined, backslash-laden segment
+    # becomes one broken entry, and EVERY bare-name command lookup breaks for
+    # the rest of that session. This is not cosmetic: it can take down `git`,
+    # `grep`, `python` -- anything resolved via PATH -- for the shell that
+    # sources it. Convert PATH-shaped values only, for POSIX target formats
+    # only; every other var (and every other format) is untouched.
+    if fmt in ("export", "dotenv", "fish"):
+        # PATHEXT is a Windows-only concept (extensionless exec resolution) with
+        # no POSIX meaning; dropped rather than emitted as noise.
+        #
+        # A handful of Windows-native var names (`ProgramFiles(x86)`,
+        # `CommonProgramFiles(Arm)`, inherited from os.environ into base_env)
+        # contain parentheses -- not a legal POSIX shell identifier. `export
+        # FOO(X86)=...` is a hard bash SYNTAX ERROR, not a bad value: sourcing
+        # it aborts the rest of the file, so every var after the first offender
+        # in iteration order never gets set either. Worse than the PATH bug,
+        # same root cause (unfiltered OS-native env reaching a POSIX target).
+        env = {
+            k: (_to_posix_path_list(v) if _looks_like_path_list(k, v) else v)
+            for k, v in env.items()
+            if k != "PATHEXT" and _POSIX_IDENTIFIER_RE.match(k)
+        }
+
     keys = sorted(env)
 
     if fmt == "json":

{dotagents_cli-0.3.0 → dotagents_cli-0.3.1}/tests/test_env_format.py

@@ -8,6 +8,7 @@ these tests only exercise pure rendering + a process-name walk.
 Run from repo root: ``python -m pytest tests/``.
 """
 
+import json
 import sys
 from pathlib import Path
 
@@ -228,3 +229,136 @@ def test_auto_resolves_to_concrete_format():
     assert resolved in _env.FORMAT_ALIASES
     # And the resolved format renders.
     assert isinstance(_format_env(SAMPLE, resolved), str)
+
+
+# --------------------------------------------------------------------------- #
+# PATH conversion for POSIX target formats (export/dotenv/fish).
+#
+# `get_environment` assembles PATH using the HOST OS's own convention -- on
+# Windows, `os.pathsep` (`;`) and backslash `Path` separators, because that is
+# what a Windows subprocess needs. A POSIX shell-sourceable format needs `:`
+# and `/`, plus MSYS2/Cygwin's drive-letter-to-mount-point form (`C:/...` ->
+# `/c/...`) for PATH LOOKUPS specifically -- slash direction alone is not
+# enough; verified live that `command -v grep` resolves through `/c/Program
+# Files/Git/usr/bin` but not `C:/Program Files/Git/usr/bin`, the same
+# directory. Left unconverted, this is exactly what the Claude SessionStart
+# hook writes into $CLAUDE_ENV_FILE -- sourcing it breaks PATH-based command
+# lookup (git, grep, python, ...) for the rest of that session.
+# --------------------------------------------------------------------------- #
+
+WINDOWS_PATH = {
+    "PATH": r"C:\Users\jose\.agents\bin;C:\Program Files\Git\usr\bin;.agents\bin",
+    "PATHEXT": ".COM;.EXE;.BAT;.CMD",
+    "AGENTS_HOME": r"C:\Users\jose\.agents",  # single path, NOT a list -- untouched
+}
+
+
+def test_export_converts_windows_path_to_posix():
+    out = _format_env(WINDOWS_PATH, "export")
+    assert (
+        'export PATH="/c/Users/jose/.agents/bin:/c/Program Files/Git/usr/bin:'
+        '.agents/bin"' in out
+    )
+
+
+def test_unc_path_keeps_double_slash_root():
+    """`\\\\server\\share` -> `//server/share`, NOT `/server/share`.
+
+    Both `Path.as_posix()` and a bare backslash-to-slash replace collapse a
+    UNC path's leading `\\\\` to a single `/`, which MSYS does not accept as
+    the UNC root -- caught by independent verification of this fix, which
+    found the collapsed form was untested.
+    """
+    from dotagents.cli.env import _to_posix_path
+
+    assert _to_posix_path("\\\\server\\share\\bin") == "//server/share/bin"
+
+
+def test_export_drops_pathext():
+    """PATHEXT has no POSIX meaning; dropped rather than emitted as garbage."""
+    out = _format_env(WINDOWS_PATH, "export")
+    assert "PATHEXT" not in out
+
+
+def test_export_leaves_single_path_values_untouched():
+    """Only PATH-LIST vars (name ends in PATH, value looks OS-native) convert --
+    a plain single-path value must not be mangled."""
+    out = _format_env(WINDOWS_PATH, "export")
+    # export JSON-quotes values, so a literal backslash is doubled on the wire;
+    # this is exactly what json.dumps(WINDOWS_PATH["AGENTS_HOME"]) produces.
+    assert json.dumps(WINDOWS_PATH["AGENTS_HOME"]) in out
+
+
+def test_dotenv_and_fish_also_convert_path():
+    for fmt in ("dotenv", "fish"):
+        out = _format_env(WINDOWS_PATH, fmt)
+        assert "/c/Program Files/Git/usr/bin" in out
+        path_line = next(l for l in out.split("\n") if l.startswith(("PATH=", "set -gx PATH")))
+        assert "\\" not in path_line
+
+
+def test_powershell_and_cmd_keep_native_path():
+    """Non-POSIX formats must NOT be touched by the conversion -- Windows
+    subprocesses need the native form, PATHEXT included."""
+    for fmt in ("powershell", "cmd"):
+        out = _format_env(WINDOWS_PATH, fmt)
+        assert r"C:\Users\jose\.agents\bin" in out
+        assert "PATHEXT" in out
+
+
+def test_json_and_yaml_keep_native_path():
+    """Data formats are for machine consumption of the RAW assembled env, not
+    for sourcing -- must not silently rewrite values."""
+    import json
+
+    out = json.loads(_format_env(WINDOWS_PATH, "json"))
+    assert out["PATH"] == WINDOWS_PATH["PATH"]
+    assert "PATHEXT" in out
+
+
+ILLEGAL_NAME_ENV = {
+    "PATH": "/usr/bin",
+    "ProgramFiles(x86)": r"C:\Program Files (x86)",
+    "CommonProgramFiles(Arm)": r"C:\Program Files (Arm)\Common Files",
+    "NORMAL_VAR": "ok",
+}
+
+
+def test_export_drops_posix_illegal_var_names():
+    """`export FOO(X86)=...` is a bash SYNTAX ERROR, not a bad value -- it
+    aborts the rest of the sourced file. A handful of real Windows env vars
+    (ProgramFiles(x86), inherited via os.environ into base_env) have this
+    shape; they must never reach a POSIX-targeted format."""
+    out = _format_env(ILLEGAL_NAME_ENV, "export")
+    assert "(" not in out
+    assert ")" not in out
+    assert "NORMAL_VAR" in out
+
+
+def test_dotenv_and_fish_also_drop_illegal_names():
+    for fmt in ("dotenv", "fish"):
+        out = _format_env(ILLEGAL_NAME_ENV, fmt)
+        assert "ProgramFiles" not in out
+        assert "NORMAL_VAR" in out
+
+
+def test_powershell_and_cmd_keep_illegal_named_vars():
+    """Non-POSIX formats have no such restriction -- must not lose data."""
+    for fmt in ("powershell", "cmd"):
+        out = _format_env(ILLEGAL_NAME_ENV, fmt)
+        assert "ProgramFiles(x86)" in out
+
+
+def test_export_output_actually_sources_in_real_bash(tmp_path):
+    """The end-to-end property that matters: the rendered output must be
+    syntactically valid POSIX shell, sourceable with no error."""
+    import subprocess
+
+    script = tmp_path / "env.sh"
+    script.write_text(_format_env(ILLEGAL_NAME_ENV, "export") + "\n", encoding="utf-8")
+    proc = subprocess.run(
+        ["sh", "-c", ". %s && echo OK" % json.dumps(str(script))],
+        capture_output=True, text=True,
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert "OK" in proc.stdout