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

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

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 +1417,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.7.3...HEAD
+[Unreleased]: https://github.com/jose-pr/dotagents/compare/v0.7.4...HEAD
+[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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dotagents-cli
-Version: 0.7.3
+Version: 0.7.4
 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.7.3 → dotagents_cli-0.7.4}/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.4}/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.4}/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. |
 

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

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

{dotagents_cli-0.7.3 → dotagents_cli-0.7.4}/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.4}/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() == []