dotagents-cli 0.7.3__tar.gz → 0.7.5__tar.gz

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.7.5] - 2026-10-14
+
+### Changed
+
+- `main()` runs through `duho.run(..., exit=False)`: it always returns the status
+  instead of raising `SystemExit` for a message, `--help` or a usage error (the
+  console script, `python -m dotagents` and `install.py` exit with it as before, with
+  the same statuses and the same text on standard error). Ctrl-C now ends with
+  status 130 and no traceback, and a closed pipe on standard output ends with
+  status 1, quietly.
+- The `duho` floor moves to `>=0.7.5,<0.8` (from `>=0.6.0,<0.7`); the vendored
+  `.pyz` pin (`build-pyz --duho-version`) moves with it. No flag, exit status or
+  output changes.
+- Command modules are loaded with duho's own `discover_commands(on_error=...)`
+  instead of a copy of its loop built on a private duho name. A module that fails
+  to import is still named in a warning and skipped, and the listing order is
+  unchanged. A command module may now import a sibling helper file by its bare
+  name.
+- `kebab_name` delegates to `duho.text.kebabcase`; its results are unchanged.
+- Discovered commands are listed in discovery order with `discover_commands(sort=False)`
+  instead of being re-sorted here, and a command that cannot build its parser is
+  found out with `duho.runtime.build_command_parser` instead of a private duho
+  helper. Output, exit statuses and which commands are skipped are unchanged.
+
+## [0.7.4] - 2026-10-14
+
+### Added
+
+- `findings index --requote` quotes, in the findings already on disk, the frontmatter
+  values YAML cannot read as they stand. Only those lines change: bodies, the other
+  lines and line endings are kept.
+
+### Changed
+
+- The private-sync guide describes the default ignore rules the overlay's
+  `sync-project` now writes, once, into the `.gitignore` of a store kept in git:
+  `scratch/`, `tmp/`, `__pycache__/`, hidden files and the machine-local overrides
+  stay out of the private repository.
+
+### Fixed
+
+- `findings` writes frontmatter any YAML parser reads. A description that opens with
+  `[` or a backtick, or holds `: `, was written bare, and a markdown viewer or any
+  other tool reading the frontmatter rejected the file. Such a value is now a
+  double-quoted string; a plain one is still written bare, and a finding written
+  before reads as it did.
+
 ## [0.7.3] - 2026-10-04
 
 ### Changed
@@ -1394,7 +1441,9 @@ 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.7.3...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.5...HEAD
+[0.7.5]: https://github.com/jose-pr/dotagents/compare/v0.7.4...v0.7.5
+[0.7.4]: https://github.com/jose-pr/dotagents/compare/v0.7.3...v0.7.4
 [0.7.3]: https://github.com/jose-pr/dotagents/compare/v0.7.2...v0.7.3
 [0.7.2]: https://github.com/jose-pr/dotagents/compare/v0.7.1...v0.7.2
 [0.7.1]: https://github.com/jose-pr/dotagents/compare/v0.7.0...v0.7.1

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.3
+Version: 0.7.5
 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
@@ -23,7 +23,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: duho<0.7,>=0.6.0
+Requires-Dist: duho<0.8,>=0.7.5
 Requires-Dist: pathlib-next<0.10,>=0.9.0
 Requires-Dist: tomli>=1.1.0; python_version < '3.11'
 Provides-Extra: dev

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/docs/guide/commands.md

@@ -442,6 +442,7 @@ dotagents findings done <name> -r "fixed in _context; test added"
 dotagents findings reopen <name>
 dotagents findings remove <name>            # an active finding recorded by mistake
 dotagents findings index                    # regenerate INDEX.md after hand edits
+dotagents findings index --requote          # ...and quote frontmatter values YAML cannot read
 dotagents findings path                     # where this scope's queue lives
 ```
 
@@ -463,6 +464,11 @@ dotagents findings path                     # where this scope's queue lives
   without a frontmatter is still listed (name = file stem, description = its
   first heading or line) and gains one the first time the command rewrites it;
   a note that is not UTF-8 is skipped with a warning and never rewritten.
+- The frontmatter is YAML a viewer or another tool can parse: a value is written
+  bare when YAML reads it back as the same text, and double-quoted otherwise (a
+  description that opens with `[` or a backtick, or holds `: `). `index --requote`
+  does the same for findings an earlier version wrote, and for hand-written ones,
+  changing only the lines that need it.
 - `add` refuses the names `index` and `readme` (on a case-insensitive
   filesystem they are `INDEX.md` / `README.md`). `done` and `reopen` refuse to
   move onto an existing file, and `remove` deletes active findings only: reopen

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/docs/guide/private-sync.md

@@ -49,6 +49,14 @@ leaves the machine is a perfectly valid setup.
   links the store instead.
 - **Copy mode** (`--copy`) makes `.agents` a real directory rather than a symlink;
   `sync-project` copies edits back into the store.
+- **Default ignore rules.** A project's `.agents/scratch/` lives inside the store, so
+  the built-in git path would commit it. The first `sync-project` on that path
+  appends a block to the store's `.gitignore` that leaves out `scratch/`, `tmp/`,
+  `__pycache__/`, hidden files (`.*`, keeping `.gitignore`, `.gitattributes`,
+  `.gitkeep`, `.ignore` and `.dotagents-install.json`) and the machine-local
+  overrides (`*.local.*`, `local.env`). It is written once, under a marker line:
+  edit the block freely and keep that line. The overlay's `kb/PRIVATE_SYNC.md` has
+  the block in full.
 
 ## Cloud sessions
 

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/pyproject.toml

@@ -35,7 +35,7 @@ classifiers = [
 # `build-pyz` vendors the floor of each of these (src/dotagents/cli/build_pyz.py);
 # raise a floor and move its pin there in the same change.
 dependencies = [
-    "duho>=0.6.0,<0.7",
+    "duho>=0.7.5,<0.8",
     "pathlib_next>=0.9.0,<0.10",
     # overlay.toml manifests and TOML registries; tomllib is stdlib from 3.11.
     'tomli>=1.1.0; python_version < "3.11"',

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/src/dotagents/AGENTS.md

@@ -40,7 +40,7 @@ and an error saying a command is required, and exits 2.
 | `path [-g] [--lib] [--format list\|native\|posix\|json]` | Print the bin dirs `env` puts on `PATH` (`--lib`: the existing lib dirs it puts on `PYTHONPATH`), highest precedence first; runs no env file. `posix` is `:`-joined, MSYS2 form on Windows. |
 | `env [-g] [--format F] [--diff] [--cache] [--into FILE]` | Print the assembled environment (`--diff`: only what differs from the caller's; `--cache`: replay the previous output while `env_cache_key` holds, up to `ENV_CACHE_TTL`; `--into FILE`: write it into FILE as the one block this command owns there) in format `F`: `auto` (default: the calling shell), `export`/`posix`/`sh`/`bash`, `dotenv`/`env`, `powershell`/`pwsh`/`ps`, `cmd`/`bat`/`batch`, `fish`, `json`, `ini`, `yaml`. |
 | `launch [AGENT] [-g] [--command PROG] [--no-context] [--inline] [--write-agent] [--dry-run] [-- ARGS...]` | Run the agent's CLI with the env applied and the context handed over; the exit code is the harness's (`128+N` on signal N). |
-| `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. |
+| `findings add\|list\|show\|done\|reopen\|remove\|index\|path [-g] [--dir D]` | The findings queue at `<store>/findings/` (`--dir` overrides): one markdown file per finding, `done` moves it to `processed/` with a required resolution, `INDEX.md` regenerated on every change. The frontmatter is valid YAML (a value is double-quoted when it must be); `index --requote` fixes values written bare in existing files, touching nothing else. |
 | `about [--json]` | `dotagents-cli <version>`, then `<distribution> <version>` per bundled (`.pyz`) or installed package. |
 | `build-pyz [--out P] [--python SHEBANG] [--duho-version V] [--pathlib-next-version V] [--extras a,b]` | Build a zipapp from a source checkout; errors elsewhere. |
 
@@ -74,7 +74,11 @@ are skipped.
 ## `dotagents.cli`
 
 - `main(argv=None) -> int` — the entry point (`dotagents` console script,
-  `python -m dotagents`, `install.py`).
+  `python -m dotagents`, `install.py`). It always returns the status and never
+  raises `SystemExit`: a `SystemExit` raised below it (a message, `--help`, a usage
+  error) comes back as its status, the message going to standard error. Ctrl-C
+  returns 130 and a closed pipe on standard output returns 1, both without a
+  traceback.
 - `class Dotagents(LoggingArgs, Cli)` — the umbrella; field `cmdspath: list[str]`.
 - `CMDS_PATH_ENV = "AGENTS_CMDS_PATH"`.
 - Re-exported for command modules: `DotAgentsArgs`, `_write_stdout` (see below).

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/src/dotagents/__init__.py

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

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/src/dotagents/_overlay/dotagents/cmds/findings.py

@@ -37,6 +37,10 @@ line, the details in the body::
 
     <the decision, evidence, or why no action was needed>
 
+The frontmatter is YAML a viewer or another tool can parse: a value is written
+bare when YAML reads it back as the same text, and as a double-quoted string
+otherwise (a description that opens with ``[`` or a backtick, or holds ``: ``).
+
 ``INDEX.md`` is one line per finding, active first, then processed -- the cheap
 thing to read at session start. Hand-written notes without frontmatter are
 still listed (name = file stem, description = first heading or line), and gain
@@ -90,6 +94,69 @@ def slugify(text: str) -> str:
     return slug
 
 
+#: A value cannot be written bare when it opens with one of these: YAML reads
+#: ``[`` as a list, a quote as a quoted string, a backtick as reserved.
+_YAML_INDICATORS = frozenset("-?:,[]{}#&*!|>'\"%@`")
+#: Bare words YAML reads as a boolean or as nothing rather than as text.
+_YAML_WORDS = frozenset(("true", "false", "yes", "no", "on", "off", "null", "~"))
+#: Line breaks to YAML that JSON leaves as they are, escaped inside a quoted value.
+_YAML_BREAKS = {"\x85": "\\u0085", "
": "\\u2028", "
": "\\u2029"}
+
+
+def _yaml_scalar(value: str) -> str:
+    """``value`` as a one-line YAML scalar: bare when YAML reads it back as the
+    same text, double-quoted when it would read something else (a list, a
+    mapping, a comment) or nothing at all."""
+    plain = (
+        value == value.strip()
+        and value[:1] not in _YAML_INDICATORS
+        and ": " not in value
+        and " #" not in value
+        and not value.endswith(":")
+        and value.lower() not in _YAML_WORDS
+        and not any(ord(c) < 32 or c == "\x7f" or c in _YAML_BREAKS for c in value)
+    )
+    if plain and value:
+        return value
+    quoted = json.dumps(value, ensure_ascii=False)  # a JSON string is a YAML one
+    for char, escape in _YAML_BREAKS.items():
+        quoted = quoted.replace(char, escape)
+    return quoted
+
+
+def _yaml_text(scalar: str) -> str:
+    """The text of a one-line scalar as :func:`_yaml_scalar` writes it. Anything
+    that is not one whole quoted string is its own text, which is how a value
+    this command wrote bare, before it quoted, still reads as it did."""
+    if len(scalar) >= 2 and scalar[0] == scalar[-1] == '"':
+        try:
+            value = json.loads(scalar)
+        except ValueError:
+            return scalar
+        return value if isinstance(value, str) else scalar
+    if len(scalar) >= 2 and scalar[0] == scalar[-1] == "'":
+        inner = scalar[1:-1]
+        if "'" not in inner.replace("''", ""):
+            return inner.replace("''", "'")
+    return scalar
+
+
+def _requoted(block: str) -> str:
+    """A frontmatter block with every bare value YAML would misread quoted.
+    A value that is already one quoted string, or reads back as itself, keeps
+    its line as it is; so do keys, order, line endings and any line that is
+    not ``key: value``."""
+    out = []
+    for line in block.splitlines(True):
+        text = line.rstrip("\r\n")
+        key, sep, value = text.partition(":")
+        bare = value.strip()
+        if sep and key.strip() and bare and _yaml_text(bare) == bare and _yaml_scalar(bare) != bare:
+            text = "%s: %s" % (key, _yaml_scalar(bare))
+        out.append(text + line[len(line.rstrip("\r\n")):])
+    return "".join(out)
+
+
 def _today() -> str:
     return datetime.date.today().isoformat()
 
@@ -153,7 +220,7 @@ class Finding:
             for line in m.group(1).splitlines():
                 key, sep, value = line.partition(":")
                 if sep and key.strip():
-                    meta[key.strip()] = value.strip()
+                    meta[key.strip()] = _yaml_text(value.strip())
             body = text[m.end():]
         else:
             body = text
@@ -178,10 +245,10 @@ class Finding:
         lines = ["---"]
         for key in _META_KEYS:
             if self.meta.get(key):
-                lines.append("%s: %s" % (key, self.meta[key]))
+                lines.append("%s: %s" % (key, _yaml_scalar(self.meta[key])))
         for key, value in self.meta.items():
             if key not in _META_KEYS and value:
-                lines.append("%s: %s" % (key, value))
+                lines.append("%s: %s" % (key, _yaml_scalar(value)))
         lines.append("---")
         body = self.body.rstrip("\r\n")
         return "\n".join(lines) + "\n\n" + (body + "\n" if body else "")
@@ -372,6 +439,26 @@ class FindingsStore:
         self.write_index()
         return path
 
+    def requote(self) -> "list[Path]":
+        """Write again every frontmatter whose values are not in the form this
+        command writes now: a description an earlier version left bare where
+        YAML needs it quoted. Only those lines change; the body, the other
+        lines and the line endings stay byte for byte. Returns the files
+        changed."""
+        changed = []
+        for finding in self.all():
+            text = finding.path.read_bytes().decode("utf-8")
+            m = _FRONTMATTER_RE.match(text[1:] if text.startswith("") else text)
+            if not m:
+                continue
+            shift = 1 if text.startswith("") else 0
+            start, end = m.start(1) + shift, m.end(1) + shift
+            block = _requoted(text[start:end])
+            if block != text[start:end]:
+                write_text_lf(finding.path, text[:start] + block + text[end:])
+                changed.append(finding.path)
+        return changed
+
     # -- index ---------------------------------------------------------------
 
     def render_index(self) -> str:
@@ -605,12 +692,24 @@ class Findings(LoggingArgs, Cli):
             return 0
 
     class Index(_Base):
-        """Regenerate INDEX.md from the files (after hand edits)."""
+        """Regenerate INDEX.md from the files (after hand edits).
+
+        `--requote` first quotes any frontmatter value YAML cannot read as it
+        stands: what an earlier version wrote for a description opening with
+        `[` or a backtick, or holding `: `."""
 
         _parsername_ = "index"
 
+        requote: bool = False
+        "Also quote frontmatter values YAML cannot read bare (bodies are not touched)."
+        ("--requote",)
+
         def __call__(self) -> int:
-            _write_stdout("%s\n" % (self.store().write_index(),))
+            store = self.store()
+            if self.requote:
+                changed = store.requote()
+                self._logger_.info("requoted the frontmatter of %d finding(s)", len(changed))
+            _write_stdout("%s\n" % (store.write_index(),))
             return 0
 
     class PathCmd(_Base):

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/src/dotagents/cli/__init__.py

@@ -30,6 +30,8 @@ from pathlib import Path
 
 import duho
 from duho import Cli, LoggingArgs
+from duho.runtime import build_command_parser
+from duho.text import kebabcase
 
 from dotagents import __version__
 
@@ -164,18 +166,7 @@ def _check_buildable(command) -> None:
     fields claiming the same flag, a flag the umbrella already owns) would
     otherwise fail every invocation. The parents are the umbrella's options,
     as in `duho.app`, so a clash with them surfaces here too."""
-    import argparse
-
-    base = Dotagents._parser_(add_help=False)
-    subparsers = argparse.ArgumentParser(add_help=False).add_subparsers()
-    if isinstance(command, type):
-        command._parser_(subparsers, parents=[base])
-        return
-    try:
-        from duho.runtime import _register_module_command
-    except ImportError:  # pragma: no cover -- a later duho without this helper
-        return
-    _register_module_command(subparsers, command, base, None, Dotagents)
+    build_command_parser(command, Dotagents)
 
 
 def _source_of(command) -> str:
@@ -207,18 +198,14 @@ def _buildable(commands, file=None) -> "list":
 def kebab_name(class_name: str) -> str:
     """A command class's default subcommand name: ``LeakCheck`` ->
     ``leak-check``, ``HTTPServer`` -> ``http-server``, ``my_cmd`` -> ``my-cmd``."""
-    import re
-
-    spaced = re.sub(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", "-", class_name)
-    return re.sub(r"[-_]+", "-", spaced).strip("-").lower()
+    return kebabcase(class_name)
 
 
 def _named(commands) -> "list":
     """``commands``, each discovered class that declares no ``_parsername_``
-    of its own given the kebab-case of its class name (:func:`kebab_name`).
-    ``_parsername_`` is optional in a command module: duho < 0.6 derived that
-    name itself, and from 0.6.0 it uses the class name as it is (``LeakCheck``),
-    which broke ``dotagents leak-check`` for a module that relied on it."""
+    of its own given the kebab-case of its class name (:func:`kebab_name`),
+    which is also the name duho gives it. Setting it makes the name readable as
+    an attribute, which the command-set keys and the tests rely on."""
     for command in commands:
         if isinstance(command, type) and "_parsername_" not in vars(command):
             command._parsername_ = kebab_name(command.__name__)
@@ -228,46 +215,19 @@ def _named(commands) -> "list":
 def _discover_modules(directory: Path) -> "list":
     """duho's per-directory discovery, made resilient per MODULE.
 
-    duho's own loop catches only ImportError/NotImplementedError per file and
-    lets anything else propagate. Discovery runs before EVERY dotagents
-    invocation (including `env`/`context` inside the SessionStart hooks), so
-    one broken user module must not take down every command: the loop is
-    mirrored here with a catch-all per file -- the bad module is named, with
-    its exception, and skipped; the rest of the directory still loads.
-    SystemExit is included because a module that `sys.exit()`s at import is
-    not an Exception. A command that imports but cannot build its parser is
-    skipped the same way (`_buildable`). Falls back to duho's own
-    per-directory unit, with a warning, if a duho release moves these
-    helpers.
-
-    Uses duho's PUBLIC `import_from_path` (duho >= 0.6.0) for the file
-    import; `_commands_in_module` has no public counterpart yet, so it stays
-    a private import (see `duho.discovery.import_from_path`'s own docstring:
-    it is the public counterpart of the `_unique_module_name` +
-    `_import_from_path` pair this module used to call directly)."""
-    try:
-        from duho.discovery import _commands_in_module, import_from_path
-    except ImportError:  # pragma: no cover -- a later duho without these internals
-        from duho.discovery import discover_commands
-
-        _LOGGER.warning(
-            "duho's discovery internals moved; a broken module in %s now skips "
-            "the whole directory, not just itself",
-            directory,
-        )
-        return _named(_buildable(discover_commands(directory)))
-    commands = []
-    for file in sorted(directory.glob("*.py")):
-        if file.name.startswith("_"):
-            continue
-        try:
-            module = import_from_path("duho._discovered." + file.stem, file)
-            found = _commands_in_module(module, stem=file.stem)
-        except (Exception, SystemExit) as exc:  # noqa: BLE001 -- see docstring
-            _LOGGER.warning("skipping command module %s: %s", file, _describe(exc))
-            continue
-        commands.extend(_named(_buildable(found, file)))
-    return commands
+    Discovery runs before EVERY dotagents invocation (including `env`/`context`
+    inside the SessionStart hooks), so one broken user module must not take
+    down every command. `on_error` is called for any exception raised importing
+    one file, `SystemExit` included (a module that `sys.exit()`s at import is
+    not an Exception): the bad module is named, with its exception, and skipped;
+    the rest of the directory still loads. A command that imports but cannot
+    build its parser is skipped the same way (`_buildable`)."""
+
+    def skip(source, exc) -> None:
+        _LOGGER.warning("skipping command module %s: %s", source, _describe(exc))
+
+    found = duho.discover_commands(directory, on_error=skip, sort=False)
+    return _named(_buildable(found))
 
 
 def _discover_dir(source, by_name: dict) -> None:
@@ -522,13 +482,14 @@ def _repoint_zipapp_sources() -> None:
 
 def main(argv=None) -> int:
     _repoint_zipapp_sources()
-    # `duho.app` (not `duho.main`) so command discovery runs; default dispatch
-    # calls each command's `__call__`. `commands=` is the resolved built-ins +
-    # discovered set.
-    return duho.app(
+    # `commands=` makes `run` use `duho.app` (not `duho.main`) so the resolved
+    # built-ins + discovered set are the commands; dispatch calls each command's
+    # `__call__`. `exit=False` returns the status, whatever ended the run.
+    return duho.run(
         Dotagents,
+        argv,
+        exit=False,
         commands=_discover(argv),
-        argv=argv,
         name="dotagents",
     )
 

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/src/dotagents/cli/build_pyz.py

@@ -73,7 +73,7 @@ class BuildPyz(LoggingArgs, Cmd):
     # stale pin here ships an artifact `pip install dotagents-cli` would refuse.
     # Pin the FLOOR of each declared range, not the latest patch -- the .pyz then
     # exercises the minimum the metadata promises.
-    duho_version: str = "0.6.0"
+    duho_version: str = "0.7.5"
     "Pinned duho version to vendor."
     ("--duho-version",)
 

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/tests/test_cli_main.py

@@ -130,7 +130,7 @@ def test_reinit_after_overlays_add_keeps_the_overlay_routing(tmp_path):
 
 
 def test_init_with_an_unknown_agent_is_a_usage_error(tmp_path):
-    assert _main(["init", "--dest", str(tmp_path / "s"), "--agents", "claud", "--no-hooks"]) == 2
+    assert _main(["init", "--dest", str(tmp_path / "s"), "--agents", "claud", "--no-hooks"]) == 1
 
 
 # --------------------------------------------------------------------------

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/tests/test_cmds_discovery.py

@@ -224,8 +224,7 @@ class LeakCheck(LoggingArgs, Cmd):
 
 
 def test_a_command_without_parsername_gets_its_kebab_class_name(monkeypatch, tmp_path, capsys):
-    """`_parsername_` is optional: duho >= 0.6.0 names such a class `LeakCheck`,
-    dotagents gives it `leak-check` (what duho < 0.6 derived)."""
+    """`_parsername_` is optional: such a class is named `leak-check`."""
     cmds = tmp_path / "extra"
     _write(cmds / "leak_check.py", UNNAMED)
     _write(cmds / "toy.py", TOY)
@@ -436,3 +435,17 @@ def test_a_module_failing_at_parser_build_does_not_take_the_cli_down(monkeypatch
     except SystemExit as exc:
         rc = exc.code
     assert rc == 0
+
+
+def test_a_directory_lists_its_commands_by_file_then_definition_order(tmp_path):
+    """The `--help` listing follows the files, not the subcommand names."""
+    template = (
+        "from duho import Cmd, LoggingArgs\n\n"
+        "class {a}(LoggingArgs, Cmd):\n    _parsername_ = '{a}'\n\n"
+        "    def __call__(self) -> int:\n        return 0\n\n"
+        "class {b}(LoggingArgs, Cmd):\n    _parsername_ = '{b}'\n\n"
+        "    def __call__(self) -> int:\n        return 0\n"
+    )
+    _write(tmp_path / "aa_first.py", template.format(a="zulu", b="alpha"))
+    _write(tmp_path / "bb_second.py", template.format(a="mike", b="bravo"))
+    assert _names(cli._discover_modules(tmp_path)) == ["zulu", "alpha", "mike", "bravo"]

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/tests/test_findings_cmd.py

@@ -336,3 +336,84 @@ def test_a_finding_named_like_the_index_is_refused(findings_mod, tmp_path):
         with pytest.raises(SystemExit, match="reserved"):
             store.add(title, body="important details")
     assert not root.exists() or not [p for p in root.iterdir() if p.suffix == ".md"]
+
+
+# --------------------------------------------------------------------------- #
+# The frontmatter is YAML another tool can read
+# --------------------------------------------------------------------------- #
+
+AWKWARD = [
+    "[low][correctness] off Linux, sniff with an interface name raises",
+    "`dotagents pyvenv` broken on the new machine",
+    "perf rule: two hosted-runner runs are not a before/after",
+    '"It compiles" is not evidence',
+    "'first', 'second' and a third",
+    '"quoted"',
+    "ends with a colon:",
+    "a marker # that starts a comment",
+    "*starred* and &anchored",
+    'a back\\slash and a "quote": both',
+    "- a leading dash",
+    "{braces} and a percent %",
+    "em dash — and an accent: é",
+    "true",
+]
+
+
+@pytest.mark.parametrize("text", AWKWARD)
+def test_any_description_is_frontmatter_yaml_can_read(findings_mod, tmp_path, text):
+    yaml = pytest.importorskip("yaml")
+    store = findings_mod.FindingsStore(tmp_path / "findings")
+    finding = store.add(text, name="x")
+    front = yaml.safe_load(finding.path.read_text(encoding="utf-8").split("---\n")[1])
+    assert front["name"] == "x" and str(front["description"]) == text
+    assert findings_mod.Finding.load(finding.path).description == text
+    assert "— %s\n" % text in store.index_path.read_text(encoding="utf-8")
+
+
+def test_a_plain_description_is_written_bare(findings_mod, tmp_path):
+    store = findings_mod.FindingsStore(tmp_path / "findings")
+    text = "bare kb/X.md refs were never inlined (3 files, 2026-09-09)"
+    raw = store.add(text).path.read_text(encoding="utf-8")
+    assert "\ndescription: %s\n" % text in raw
+
+
+@pytest.mark.parametrize("text", [
+    "[low][api] a consumer: rewrites `x`",
+    '"It compiles" is not evidence',
+    "'one', 'two'",
+    '"a" and "b"',
+])
+def test_a_finding_written_bare_still_reads_as_it_did(findings_mod, tmp_path, text):
+    """What an earlier version wrote: the description as typed, whatever it held."""
+    path = tmp_path / "findings" / "old.md"
+    path.parent.mkdir(parents=True)
+    path.write_bytes(("---\nname: old\ndescription: %s\nstatus: active\n---\n\nbody\n" % text).encode("utf-8"))
+    assert findings_mod.Finding.load(path).description == text
+
+
+def test_index_requote_changes_only_the_values_yaml_cannot_read(findings_mod, tmp_path, capsys):
+    yaml = pytest.importorskip("yaml")
+    root = tmp_path / "findings"
+    (root / "processed").mkdir(parents=True)
+    bad = root / "processed" / "bad.md"  # CRLF, odd spacing, blank lines: all kept
+    bad.write_bytes(b"---\r\nname: bad\r\ndescription: [low][api] a: b\r\nstatus: processed\r\n---\r\n\r\n\r\nbody kept  \r\n\r\n\r\n")
+    kept = {
+        root / "quoted.md": b'---\nname: quoted\ndescription: "already: quoted"\n---\nbody\n',
+        root / "plain.md": b"---\nname: plain\ndescription:   nothing to do\nextra: 1\n---\n\nbody\n",
+        root / "note.md": b"# a hand note\n\n---\nnot: [frontmatter\n---\n",
+    }
+    for path, data in kept.items():
+        path.write_bytes(data)
+
+    assert _run(findings_mod.Findings.Index, dir=root, requote=True) == 0
+    assert capsys.readouterr().out.strip() == str(root / "INDEX.md")
+
+    assert bad.read_bytes() == (
+        b'---\r\nname: bad\r\ndescription: "[low][api] a: b"\r\nstatus: processed\r\n---\r\n\r\n\r\nbody kept  \r\n\r\n\r\n')
+    assert yaml.safe_load(bad.read_bytes().decode().split("---\r\n")[1])["description"] == "[low][api] a: b"
+    for path, data in kept.items():
+        assert path.read_bytes() == data, path.name
+    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() == []

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/tests/test_fix_cli.py

@@ -211,31 +211,6 @@ def test_a_command_clashing_with_an_umbrella_flag_is_skipped(monkeypatch, tmp_pa
     assert cli.main(["about"]) == 0
 
 
-def test_moved_duho_internals_are_reported_not_silent(monkeypatch, tmp_path, caplog):
-    import builtins
-
-    cmds = tmp_path / "cmds"
-    cmds.mkdir()
-    (cmds / "good.py").write_text(GOOD, encoding="utf-8")
-    real_import = builtins.__import__
-
-    def renamed(name, globals=None, locals=None, fromlist=(), level=0):
-        # What a duho release that renamed its remaining private helper looks
-        # like to `from duho.discovery import _commands_in_module, ...` --
-        # and only to it. `import_from_path` is duho's public counterpart
-        # (duho >= 0.6.0) and stays importable; `_commands_in_module` has no
-        # public counterpart yet, so it is the one still exposed to this risk.
-        if name == "duho.discovery" and "_commands_in_module" in (fromlist or ()):
-            raise ImportError("cannot import name '_commands_in_module'")
-        return real_import(name, globals, locals, fromlist, level)
-
-    monkeypatch.setattr(builtins, "__import__", renamed)
-    with caplog.at_level(logging.WARNING):
-        commands = cli._discover_modules(cmds)
-    assert "good" in _names(commands)
-    assert any("internals moved" in r.getMessage() for r in caplog.records)
-
-
 # --------------------------------------------------------------------------- #
 # The zipapp-repointed module list is derived, not hand-kept
 # --------------------------------------------------------------------------- #

{dotagents_cli-0.7.3 → dotagents_cli-0.7.5}/tests/test_fix_init.py

@@ -246,16 +246,15 @@ def test_a_bom_in_settings_json_is_accepted_and_not_written_back(tmp_path):
 
 
 @pytest.mark.parametrize("content", [b"{not json", b"\xff\xfe{}"])
-def test_a_corrupt_settings_file_stops_init_before_anything_is_written(content):
+def test_a_corrupt_settings_file_stops_init_before_anything_is_written(content, capsys):
     """The error fired after AGENTS.md and the CLAUDE.md include were written,
     leaving a half-initialised store."""
     settings = Path.home() / ".claude" / "settings.json"
     settings.parent.mkdir(parents=True)
     settings.write_bytes(content)
 
-    with pytest.raises(SystemExit) as exc:
-        cli.main(["init", "-g", "--agents", "claude"])
-    assert str(settings) in str(exc.value)
+    assert cli.main(["init", "-g", "--agents", "claude"]) == 1
+    assert str(settings) in capsys.readouterr().err
     assert not (Path.home() / ".agents").exists()
     assert not (Path.home() / ".claude" / "CLAUDE.md").exists()
     assert settings.read_bytes() == content