dotagents-cli 0.8.1__tar.gz → 0.8.2__tar.gz

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.2] - 2026-10-25
+
+### Fixed
+
+- `findings` (and `init` / `overlays`) run from inside a project's `.agents`, such as
+  `<project>/.agents/findings`, target that project. They used to write a second
+  `.agents` inside the store. Deeper than a top-level directory of the user store,
+  where no project can be named, they refuse instead of writing there.
+- `findings` keeps a hand-written `INDEX.md`: before the first regeneration it is
+  copied to `INDEX.md.handwritten`, with a warning.
+- The routing note above overlay paths no longer suggests `dotagents env` for
+  reading an overlay root (it prints the whole environment, secrets included); it
+  says to read just the variable.
+
+- The `sh` wrapper `init` writes into `<store>/bin/dotagents` works from another
+  system that shares the store, such as WSL reading a Windows store. It ran the
+  interpreter recorded by `init`, a Windows path there; where that interpreter
+  does not run it now takes the store's agents' venv for that OS and machine
+  (`.pyvenv/<version>-<os>-<arch>`), else `python3`, and converts a recorded
+  `C:/...` pyz path with `wslpath`.
+
 ## [0.8.1] - 2026-10-21
 
 ### Added
@@ -1546,7 +1567,8 @@ Patch release: the PATH/POSIX-conversion fix above (the only change since 0.3.0)
   affected module sources (`dotagents.cli`, `duho.presets`) to extracted temp files
   before dispatch; a no-op for a plain install.
 
-[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.8.1...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.8.2...HEAD
+[0.8.2]: https://github.com/jose-pr/dotagents/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/jose-pr/dotagents/compare/v0.8.0...v0.8.1
 [0.8.0]: https://github.com/jose-pr/dotagents/compare/v0.7.6...v0.8.0
 [0.7.6]: https://github.com/jose-pr/dotagents/compare/v0.7.5...v0.7.6

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.8.1
+Version: 0.8.2
 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

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/docs/guide/private-sync.md

@@ -11,13 +11,19 @@ overlay is what makes them exist; a plain dotagents has no private-sync surface
 
 ## The idea
 
-Your global config store **is** a private git repo. Its root is the per-user config;
-a `projects/<name>/` tree inside it holds each project's private payload. For a
-checked-out project, its `.agents` directory is a **symlink** into the store (the
-project's `.gitignore` already excludes `.agents` per the Leakage rule, so the link
+Your global config store **is** a private git repo, and its `main` branch is the
+per-user config. Each project's private payload is a **branch** of it, named after
+the project, and the project's `.agents` directory is a git worktree on that branch
+(the project's `.gitignore` already excludes `.agents` per the Leakage rule, so it
 never lands in the public repo). `<name>` defaults to the project's basename, so a
-local checkout and a cloud checkout of the same project resolve to the same store
-entry.
+local checkout and a cloud checkout of the same project resolve to the same branch.
+
+That branch can live elsewhere: `link-project --store-repo self` keeps it on the
+project's own repository (branch `agents`), and `--store-repo <url>` on any other,
+such as a team account's (cloned into `.agents`); `--store-branch` names the branch.
+The choice is recorded in the config repo, so every machine links the project the
+same way. A store kept as a `projects/<name>/` directory, symlinked into the
+project, still works and is kept by a project that already has one.
 
 The store's installed overlays can travel two ways:
 
@@ -39,11 +45,12 @@ dotagents overlays add private-sync -g \
   --repo "https://github.com/jose-pr/dotagents.git@repo#overlays"   # commands + kb + hooks
 
 # link-project / sync-project come FROM that overlay -- run `overlays add` first.
-dotagents link-project .   # symlink this project's .agents into its store
+dotagents link-project .   # check this project's store branch out at .agents
                            #   (an existing real .agents/ is adopted on the
-                           #    first link; --copy mirrors it as a real dir
-                           #    for no-symlink systems)
-dotagents sync-project -m "msg"   # git pull --rebase / commit / push the store
+                           #    first link)
+dotagents link-project . --store-repo self             # ...on the project's own repo
+dotagents link-project . --store-repo <team-repo-url>  # ...on another repo
+dotagents sync-project --project . -m "msg"   # commit / push the project's branch, then the config
 dotagents sync-project --remote <url> -m init   # one-command bootstrap
 ```
 

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/AGENTS.md

@@ -722,8 +722,11 @@ objects `{"matcher"?: str, "hooks": [{"type": "command", "command": str, ...}]}`
 
 ## `dotagents._wrappers`
 
-- `POSIX_TEMPLATE`, `POSIX_TEMPLATE_REL` (pyz path relative to the wrapper),
-  `POSIX_TEMPLATE_MODULE` (`"<python>" -m dotagents`) — the `sh` wrapper bodies.
+- `POSIX_TEMPLATE` — the `sh` wrapper body, for a `.pyz` (absolute, or relative
+  to the wrapper) or `-m dotagents`. It runs the recorded interpreter; where that
+  does not run (a Windows store read from WSL) it takes the store's agents' venv
+  for this OS and machine (`.pyvenv/*-<os>-<arch>/bin/python`), else `python3`,
+  and turns a recorded `C:/...` pyz path into a local one with `wslpath`.
 - `write_wrappers(bin_dir, pyz_path, python=None, *, relative=False) -> list[Path]` —
   `dotagents` (sh) and `dotagents.cmd`, both always, running the `.pyz`.
 - `write_module_wrappers(bin_dir, python=None) -> list[Path]` — both forms running

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/__init__.py

@@ -1,3 +1,3 @@
 """dotagents: installable CLI for the dotagents agent-config payload."""
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/_overlay/dotagents/cmds/findings.py

@@ -493,11 +493,32 @@ class FindingsStore:
         return "\n".join(lines) + "\n"
 
     def write_index(self) -> Path:
+        _keep_handwritten(self.index_path, "Regenerated by `dotagents findings`")
         # Atomic: an agent may be reading the index while a change rewrites it.
         write_text_lf(self.index_path, self.render_index(), atomic=True)
         return self.index_path
 
 
+def _keep_handwritten(index: Path, marker: str) -> None:
+    """Copy an index this command did not write (it lacks ``marker``) to
+    ``INDEX.md.handwritten`` before it is regenerated, saying so. The backup is
+    not ``*.md``, so it is never read as an entry."""
+    try:
+        text = index.read_text(encoding="utf-8")
+    except OSError:
+        return
+    if marker in text:
+        return
+    backup = index.with_name(index.name + ".handwritten")
+    n = 1
+    while backup.exists():
+        n += 1
+        backup = index.with_name("%s.handwritten-%d" % (index.name, n))
+    write_text_lf(backup, text)
+    logging.getLogger("dotagents").warning(
+        "%s was written by hand; it is kept as %s and regenerated", index, backup.name)
+
+
 # --------------------------------------------------------------------------- #
 # The command
 # --------------------------------------------------------------------------- #

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/_overlays.py

@@ -1166,9 +1166,10 @@ def _compose_block(base_text: str, overlays, logger) -> str:
 #: Emitted once above overlay routing lines that use the per-overlay root vars.
 OVERLAY_ROOT_NOTE = (
     "Overlay paths below use `$<NAME>_OVERLAY_ROOT` -- an environment variable "
-    "`dotagents env` exports per installed overlay (its install dir); resolve it "
-    "in a shell (`echo $ENGINEERING_OVERLAY_ROOT`; PowerShell `$env:ENGINEERING_OVERLAY_ROOT`) "
-    "before opening the file with a file tool."
+    "already set in your shell for each installed overlay (its install dir); read "
+    "just that one (`echo $ENGINEERING_OVERLAY_ROOT`; PowerShell "
+    "`$env:ENGINEERING_OVERLAY_ROOT`) before opening the file with a file tool, "
+    "never the whole environment (`dotagents env` prints secrets)."
 )
 
 

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/_scope.py

@@ -505,6 +505,27 @@ def _project_containing(start: Path) -> Path:
     return start
 
 
+def _outside_store(cwd: Path) -> Path:
+    """``cwd``, or -- when it lies inside a ``.agents`` directory -- the project
+    that ``.agents`` belongs to (the parent of the outermost one): a command run
+    from ``<project>/.agents/findings`` means that project, never a second
+    ``.agents`` inside its store. Deeper than a top-level directory of the user
+    store (a linked project store reached through its target) there is no
+    project to name, so that is refused rather than written into the store."""
+    parts = cwd.parts
+    if ".agents" not in parts:
+        return cwd
+    index = parts.index(".agents")
+    root = Path(*parts[:index]) if index else cwd
+    store = resolve_user_store()
+    if _same_path(root / ".agents", store) and len(parts) > index + 2:
+        raise SystemExit(
+            "error: %s is inside the agents store %s, not a project; run from the "
+            "project's root (or pass --dir / --agents-dir)" % (cwd, store)
+        )
+    return root
+
+
 def install_project_root() -> Path:
     """The project root the WRITING commands (``init``, ``overlays``,
     ``findings``) target when none is passed explicitly.
@@ -519,8 +540,10 @@ def install_project_root() -> Path:
 
     ``env`` / ``context`` keep :func:`project_root_default`, where the pin wins
     regardless of the cwd: what they read must stay stable across the
-    subdirectories a session's commands run in."""
-    cwd = Path.cwd()
+    subdirectories a session's commands run in.
+
+    A cwd inside a ``.agents`` counts as its project's root (:func:`_outside_store`)."""
+    cwd = _outside_store(Path.cwd())
     for var in ("AGENTS_PROJECT_ROOT", *_HARNESS_PROJECT_ROOT_VARS):
         value = os.environ.get(var)
         if not value:

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/src/dotagents/_wrappers.py

@@ -6,20 +6,39 @@ import stat
 import sys
 from pathlib import Path
 
-POSIX_TEMPLATE = '#!/bin/sh\nexec "{python}" "{pyz}" "$@"\n'
-
-# Relative forms: resolve the pyz from the wrapper's own directory, so moving or
-# copying the scope dir does not break the command.
-# `readlink -f` so a wrapper run through a symlink (into ~/.local/bin, say)
-# still finds the pyz beside the real file; plain `$0` where readlink -f fails.
-POSIX_TEMPLATE_REL = (
-    '#!/bin/sh\nd=$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")\n'
-    'exec "{python}" "$d/{pyz}" "$@"\n'
+# The sh wrapper. `{target}` is what the interpreter runs: the pyz (absolute,
+# or `"$d/..."` relative to the wrapper's own directory, so moving the scope dir
+# does not break it) or `-m dotagents` for a plain install. `readlink -f` so a
+# wrapper run through a symlink still finds what is beside the real file.
+#
+# The interpreter recorded is the one of the system that ran `init`. A store
+# shared with another system -- WSL reading a Windows store -- reaches a
+# recorded path that does not run there; the wrapper then takes that system's
+# own: the store's agents' venv for this OS and machine (`.pyvenv/*-<os>-<arch>`,
+# the naming `dotagents._pyvenv` uses), else `python3`, and a recorded
+# `C:/...` pyz path goes through `wslpath`.
+POSIX_TEMPLATE = (
+    '#!/bin/sh\n'
+    'd=$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")\n'
+    'py="{python}"\n'
+    'set -- {target} "$@"\n'
+    'if [ ! -x "$py" ]; then\n'
+    '  case "$(uname -s)" in Darwin) os=darwin ;; *) os=posix ;; esac\n'
+    '  py=\n'
+    '  for v in "$d"/../.pyvenv/*-"$os"-"$(uname -m)"/bin/python; do\n'
+    '    [ -x "$v" ] && py=$v\n'
+    '  done\n'
+    '  [ -n "$py" ] || py=$(command -v python3 || command -v python) || {{\n'
+    '    echo "dotagents: no Python interpreter found" >&2; exit 127; }}\n'
+    '  case "$1" in [A-Za-z]:/*) if command -v wslpath >/dev/null 2>&1; then\n'
+    '    p=$(wslpath -u "$1"); shift; set -- "$p" "$@"; fi ;; esac\n'
+    'fi\n'
+    'exec "$py" "$@"\n'
 )
 
-# Module mode: a plain (pip / editable) install has no pyz to point at, so the
-# wrapper runs the package through the interpreter that has it installed.
-POSIX_TEMPLATE_MODULE = '#!/bin/sh\nexec "{python}" -m dotagents "$@"\n'
+
+def _posix_wrapper(python: str, target: str) -> str:
+    return POSIX_TEMPLATE.format(python=Path(python).as_posix(), target=target)
 
 
 def _cmd_safe(path: str) -> str:
@@ -88,7 +107,7 @@ def write_module_wrappers(bin_dir: Path, python: "str | None" = None) -> "list[P
     python = python or sys.executable
     sh_path, cmd_path = bin_dir / "dotagents", bin_dir / "dotagents.cmd"
     with open(sh_path, "w", encoding="utf-8", newline="") as f:
-        f.write(POSIX_TEMPLATE_MODULE.format(python=Path(python).as_posix()))
+        f.write(_posix_wrapper(python, "-m dotagents"))
     if os.name != "nt":
         sh_path.chmod(sh_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
     _write_cmd(cmd_path, '"%s" -m dotagents %%*' % _cmd_safe(str(python)))
@@ -149,17 +168,9 @@ def write_wrappers(
     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()
-                )
-            )
+            f.write(_posix_wrapper(python, '"$d/%s"' % rel_pyz.as_posix()))
         else:
-            f.write(
-                POSIX_TEMPLATE.format(
-                    python=Path(python).as_posix(), pyz=pyz_path.as_posix()
-                )
-            )
+            f.write(_posix_wrapper(python, '"%s"' % 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)

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/tests/test_findings_cmd.py

@@ -417,3 +417,17 @@ def test_index_requote_changes_only_the_values_yaml_cannot_read(findings_mod, tm
     assert "— [low][api] a: b" in (root / "INDEX.md").read_text(encoding="utf-8")
     # A second pass has nothing left to do.
     assert findings_mod.FindingsStore(root).requote() == []
+
+
+def test_a_hand_written_index_is_kept_before_it_is_regenerated(findings_mod, tmp_path):
+    root = tmp_path / "findings"
+    root.mkdir()
+    (root / "INDEX.md").write_text("# My own index\n\n- evidence line\n", encoding="utf-8")
+    store = findings_mod.FindingsStore(root)
+    store.add("First problem", body="b")
+    kept = root / "INDEX.md.handwritten"
+    assert kept.read_text(encoding="utf-8") == "# My own index\n\n- evidence line\n"
+    assert "Regenerated by `dotagents findings`" in (root / "INDEX.md").read_text(encoding="utf-8")
+    store.add("Second problem", body="b")  # a generated index is not backed up again
+    assert sorted(p.name for p in root.iterdir() if "handwritten" in p.name) == ["INDEX.md.handwritten"]
+    assert [f.name for f in store.active()] == ["first-problem", "second-problem"]

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/tests/test_fix_scope_context.py

@@ -97,6 +97,33 @@ def test_a_store_that_appears_twice_is_walked_once(tmp_path):
 # scope-context-03: a pin the cwd has left is reported by the writing commands
 # --------------------------------------------------------------------------
 
+def test_a_cwd_inside_a_project_store_means_that_project(tmp_path, monkeypatch):
+    """`dotagents findings index` run from `<project>/.agents/findings` wrote a
+    second `.agents` inside the store; the project is the one holding it."""
+    project = tmp_path / "proj"
+    (project / ".agents" / "findings").mkdir(parents=True)
+    monkeypatch.chdir(project / ".agents" / "findings")
+    assert _scope.resolve_scope(False).agents_root == project / ".agents"
+    # Pinned elsewhere, the same.
+    monkeypatch.setenv("AGENTS_PROJECT_ROOT", str(tmp_path / "other"))
+    assert _scope.resolve_scope(False).agents_root == project / ".agents"
+
+
+def test_a_cwd_deep_in_the_user_store_is_refused(tmp_path, monkeypatch):
+    """Reached through a linked store's target, the cwd names no project; it is
+    refused rather than written into the store as `.agents/.agents`."""
+    store = tmp_path / "home" / ".agents"
+    monkeypatch.setenv("AGENTS_HOME", str(store))
+    deep = store / "projects" / "app" / "findings"
+    deep.mkdir(parents=True)
+    monkeypatch.chdir(deep)
+    with pytest.raises(SystemExit, match="inside the agents store"):
+        _scope.resolve_scope(False)
+    # A top-level directory of the store is the store itself: the user scope.
+    monkeypatch.chdir(store / "projects")
+    assert _scope.resolve_scope(False).agents_root == store
+
+
 def test_writing_outside_the_pinned_root_warns(tmp_path, monkeypatch, caplog):
     proj_a, proj_b = tmp_path / "projA", tmp_path / "projB"
     (proj_a / "sub").mkdir(parents=True)

{dotagents_cli-0.8.1 → dotagents_cli-0.8.2}/tests/test_wrappers.py

@@ -74,8 +74,7 @@ def test_relative_declines_a_pyz_outside_the_scope(tmp_path):
     write_wrappers(tmp_path / "scope" / "bin", pyz, relative=True)
 
     sh = (tmp_path / "scope" / "bin" / "dotagents").read_text(encoding="utf-8")
-    assert ".." not in sh, "must not emit a ../ chain"
-    assert pyz.as_posix() in sh
+    assert 'set -- "%s"' % pyz.as_posix() in sh, "the pyz must be absolute, not a ../ chain"
 
 
 def test_absolute_by_default(tmp_path):
@@ -83,7 +82,7 @@ def test_absolute_by_default(tmp_path):
     write_wrappers(tmp_path / "bin", pyz)
     sh = (tmp_path / "bin" / "dotagents").read_text(encoding="utf-8")
     assert pyz.as_posix() in sh
-    assert "dirname" not in sh
+    assert '"$d/' not in sh, "the pyz path is absolute, not relative to the wrapper"
 
 
 def test_crlf_in_cmd_and_lf_in_sh(tmp_path):
@@ -159,6 +158,33 @@ def test_relative_falls_back_when_no_relative_path_exists(tmp_path, monkeypatch)
     assert pyz.as_posix() in sh, "must fall back to an absolute path, not crash"
 
 
+@pytest.mark.skipif(os.name == "nt", reason="the fallback is for a system where the recorded interpreter does not run")
+def test_a_recorded_interpreter_that_does_not_run_falls_back_to_the_store_venv(tmp_path):
+    """A store shared with another system (WSL reading a Windows store): the
+    recorded interpreter is not there, so the store's agents' venv for this OS
+    and machine runs the pyz."""
+    import platform
+
+    store = tmp_path / "store"
+    store.mkdir()
+    pyz = store / "dotagents.pyz"
+    pyz.write_text(PROBE, encoding="utf-8")
+    write_wrappers(store / "bin", pyz, python="C:/Not/Here/python.exe", relative=True)
+    os_name = "darwin" if sys.platform == "darwin" else "posix"
+    venv_python = store / ".pyvenv" / ("3.99.0-%s-%s" % (os_name, platform.machine())) / "bin" / "python"
+    venv_python.parent.mkdir(parents=True)
+    venv_python.symlink_to(sys.executable)
+    _run_sh(store / "bin" / "dotagents", tmp_path)
+
+
+@pytest.mark.skipif(os.name == "nt", reason="the fallback is for a system where the recorded interpreter does not run")
+def test_with_no_store_venv_the_fallback_is_python3(tmp_path):
+    pyz = tmp_path / "dotagents.pyz"
+    pyz.write_text(PROBE, encoding="utf-8")
+    write_wrappers(tmp_path / "bin", pyz, python="C:/Not/Here/python.exe")
+    _run_sh(tmp_path / "bin" / "dotagents", tmp_path)
+
+
 def test_module_wrappers_run_the_installed_package(tmp_path):
     r"""A plain install has no pyz: `init` wrote no wrappers at all, and the
     PowerShell hooks called a `<store>\bin\dotagents.cmd` that never existed."""