dotagents-cli 0.3.0__py3-none-any.whl

dotagents/_hooks.py

@@ -0,0 +1,172 @@
+"""Merge dotagents' hooks into an agent's ``settings.json`` without disturbing it.
+
+An agent's settings file belongs to the **user**: it may carry unrelated keys and
+hooks we did not write, in shapes we did not choose. So every function here is
+additive and defensive -- foreign entries survive verbatim, malformed ones are
+coerced or dropped rather than raising, and re-running is a no-op.
+
+Idempotence is the property that matters: ``dotagents init`` is re-run often, and a
+merge that appended a duplicate hook each time would quietly grow the file until
+the agent ran our command N times per session.
+
+The schema (verified against current Claude Code docs, 2026-07-24) is::
+
+    hooks: { "<Event>": [ { "matcher"?: str,
+                            "hooks": [ {"type": "command", "command": str,
+                                        "statusMessage"?: str} ] } ] }
+
+``hooks.<Event>`` is a **list of matcher-objects**, each holding its own ``hooks``
+list -- not a flat list of commands. ``statusMessage`` is a supported key.
+
+Pure stdlib (``json``/``pathlib``) so it works in a plain ``pip install`` and inside
+the ``.pyz``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+
+def build_hook_entry(
+    command: str,
+    *,
+    matcher: "Optional[str]" = None,
+    status_message: "Optional[str]" = None,
+) -> "dict[str, Any]":
+    """One matcher-object wrapping a single ``type: command`` hook.
+
+    ``matcher``/``statusMessage`` are omitted entirely when None rather than
+    written as null -- an absent key is the documented "no matcher" form.
+    """
+    hook: "dict[str, Any]" = {"type": "command", "command": command}
+    if status_message:
+        hook["statusMessage"] = status_message
+    entry: "dict[str, Any]" = {}
+    if matcher is not None:
+        entry["matcher"] = matcher
+    entry["hooks"] = [hook]
+    return entry
+
+
+def _has_status(entry: Any, status_message: str) -> bool:
+    """True if `entry` carries a hook stamped with our `statusMessage`.
+
+    The status message is a stable label we choose, so it identifies our hook
+    across revisions of the command text -- unlike the command itself, which
+    changes and would leave the old version orphaned beside the new one.
+    """
+    if not isinstance(entry, dict):
+        return False
+    nested = entry.get("hooks")
+    if not isinstance(nested, list):
+        return False
+    return any(
+        isinstance(h, dict) and h.get("statusMessage") == status_message
+        for h in nested
+    )
+
+
+def _is_ours(entry: Any, command: str) -> bool:
+    """True if `entry` is a well-formed matcher-object containing our command."""
+    if not isinstance(entry, dict):
+        return False
+    nested = entry.get("hooks")
+    if not isinstance(nested, list):
+        return False
+    return any(
+        isinstance(h, dict) and h.get("command") == command for h in nested
+    )
+
+
+def merge_hook(
+    existing: Any,
+    command: str,
+    *,
+    matcher: "Optional[str]" = None,
+    status_message: "Optional[str]" = None,
+) -> "tuple[list, bool]":
+    """Fold our hook into `existing`, returning ``(normalized_list, changed)``.
+
+    Rules, in order:
+
+    * absent / not-a-list ``existing`` -> a fresh single-entry list (changed).
+    * an entry already carrying our exact ``command`` -> kept as-is; the first
+      such entry wins and any later duplicate is dropped (changed), so repeated
+      ``init`` runs converge instead of accumulating.
+    * foreign entries -> preserved verbatim, untouched, in their original order.
+    * malformed entries (bare strings, dicts without a ``hooks`` list, non-dicts)
+      -> dropped, flagged changed. Never raises: a user's hand-edited settings
+      file must not make ``init`` explode.
+
+    ``status_message`` doubles as our hook's IDENTITY. An entry carrying the same
+    status message is treated as an older shape of our own hook and replaced, not
+    left beside the new one. Without that, dedup is by exact command string, so
+    revising the command we write silently orphans the previous version and the
+    old (often broken) hook keeps running next to the new one. The status message
+    is a stable label we choose, which makes it a better key than the command text
+    it describes.
+    """
+    if not isinstance(existing, list):
+        # None/absent is the common case; a non-list is a malformed file we replace.
+        return [build_hook_entry(command, matcher=matcher, status_message=status_message)], True
+
+    normalized: list = []
+    changed = False
+    seen_ours = False
+
+    for entry in existing:
+        if _is_ours(entry, command):
+            if seen_ours:
+                changed = True  # collapse duplicates of our own command
+                continue
+            seen_ours = True
+            normalized.append(entry)
+            continue
+        if status_message and _has_status(entry, status_message):
+            changed = True  # an older shape of OUR hook -- replace, don't duplicate
+            continue
+        if not isinstance(entry, dict) or not isinstance(entry.get("hooks"), list):
+            changed = True  # malformed -- drop it
+            continue
+        normalized.append(entry)  # foreign but well-formed: leave alone
+
+    if not seen_ours:
+        normalized.append(
+            build_hook_entry(command, matcher=matcher, status_message=status_message)
+        )
+        changed = True
+
+    return normalized, changed
+
+
+def load_settings(path: Path) -> "dict[str, Any]":
+    """Read a settings.json, tolerating absence but never corruption.
+
+    A missing or empty file yields ``{}``. Invalid JSON raises ``SystemExit`` with
+    the path and parse error: silently starting from ``{}`` there would overwrite a
+    user's whole settings file on the next write.
+    """
+    if not path.is_file():
+        return {}
+    raw = path.read_text(encoding="utf-8").strip()
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(
+            "error: %s is not valid JSON (%s). Fix or move it, then re-run." % (path, exc)
+        ) from exc
+    if not isinstance(data, dict):
+        raise SystemExit("error: %s must contain a JSON object, got %s" % (path, type(data).__name__))
+    return data
+
+
+def write_settings(path: Path, data: "dict[str, Any]", *, dry_run: bool = False) -> None:
+    """Write settings.json with a stable 2-space indent and trailing newline."""
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")

dotagents/_merge.py

@@ -0,0 +1,122 @@
+"""Managed-block merge for `init`'s AGENTS.md/CLAUDE.md (D-init-merge).
+
+`init` must never clobber a user-customized AGENTS.md. Content owned by dotagents
+is delimited by literal marker lines and treated as a block *within* the file:
+create if missing, prepend if present-without-markers, refresh-in-place if the
+markers are already there. Detection is by marker presence only, never by prose
+matching, so it survives user reformatting.
+"""
+
+import shutil
+import time
+from pathlib import Path
+
+BEGIN_MARKER = "<!-- dotagents:begin -->"
+END_MARKER = "<!-- dotagents:end -->"
+
+
+def _extract_block(
+    text: str, begin_marker: str = BEGIN_MARKER, end_marker: str = END_MARKER
+) -> str:
+    """Return the managed block's inner text (without the marker lines) from
+    a skeleton/template file that is itself fully marker-wrapped."""
+    start = text.index(begin_marker)
+    end = text.index(end_marker)
+    return text[start : end + len(end_marker)]
+
+
+def _backup(target: Path, backup_root: Path) -> None:
+    backup_root.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(target, backup_root / target.name)
+
+
+def merge_block(
+    target: Path,
+    block_source_text: str,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+    backup_root: "Path | None" = None,
+    begin_marker: str = BEGIN_MARKER,
+    end_marker: str = END_MARKER,
+    append: bool = False,
+) -> str:
+    """Merge `block_source_text` (a fully marker-wrapped skeleton file's
+    contents) into `target`, returning the branch taken:
+    "created" / "block-inserted" / "block-refreshed" / "replaced (--force, backed up)".
+
+    Never overwrites content outside the markers unless `force` is True (then
+    the whole file is replaced, after being backed up to `backup_root` if the
+    target pre-exists).
+
+    `begin_marker`/`end_marker` default to the Markdown/HTML comment pair; pass a
+    different pair for other comment syntaxes (e.g. `#`-prefixed markers for TOML).
+
+    `append` puts the block at the END of an existing file rather than the start.
+    Required for TOML: a `[table]` header captures every key line that follows it,
+    so prepending a table would silently swallow the user's existing top-level keys
+    into our table.
+    """
+    block = _extract_block(block_source_text, begin_marker, end_marker)
+
+    if force:
+        existed = target.exists()
+        if existed and backup_root is not None:
+            if not dry_run:
+                _backup(target, backup_root)
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(block_source_text, encoding="utf-8")
+        return "replaced (--force, backed up)" if existed else "created"
+
+    if not target.exists():
+        if not dry_run:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(block_source_text, encoding="utf-8")
+        return "created"
+
+    existing = target.read_text(encoding="utf-8")
+
+    if begin_marker in existing and end_marker in existing:
+        start = existing.index(begin_marker)
+        end = existing.index(end_marker) + len(end_marker)
+        new_text = existing[:start] + block + existing[end:]
+        if new_text == existing:
+            return "skipped (present)"
+        if not dry_run:
+            target.write_text(new_text, encoding="utf-8")
+        return "block-refreshed"
+
+    if append:
+        sep = "" if existing.endswith("\n") else "\n"
+        new_text = existing + sep + "\n" + block + "\n"
+    else:
+        new_text = block + "\n\n" + existing
+    if not dry_run:
+        target.write_text(new_text, encoding="utf-8")
+    return "block-inserted"
+
+
+def merge_claude_md(
+    target: Path,
+    block_source_text: str,
+    *,
+    force: bool = False,
+    dry_run: bool = False,
+    backup_root: "Path | None" = None,
+) -> str:
+    """Same managed-block rule, but for the CLAUDE.md one-liner: if the file
+    already contains an `@AGENTS.md` reference (any form), leave it untouched
+    (branch "skipped (present)") instead of requiring exact marker match --
+    a bare `@AGENTS.md` file written by hand still counts as "present"."""
+    if not force and target.exists():
+        existing = target.read_text(encoding="utf-8")
+        if "@AGENTS.md" in existing:
+            return "skipped (present)"
+    return merge_block(
+        target, block_source_text, force=force, dry_run=dry_run, backup_root=backup_root
+    )
+
+
+def timestamped_backup_root(dest: Path) -> Path:
+    return dest / "install_backup" / time.strftime("%Y%m%d-%H%M%S")

dotagents/_overlay/AGENTS.md

@@ -0,0 +1,31 @@
+<!-- dotagents:begin -->
+# Agent Directives
+
+Startup: annotate that you read `~/.agents/AGENTS.md`.
+
+## Always-on rules
+- **Permissions**: read any `AGENTS.md`; full read/write/create/delete inside any
+  `.agents/` directory and this config directory (`~/.agents` unless installed
+  elsewhere) — never ask.
+- **Read the local `AGENTS.md`**: before working in a directory, read the ones
+  governing it — at each level from this global file down to that directory, any of
+  `AGENTS.md`, `AGENTS.local.md`, `.agents/AGENTS.md`, `.agents/AGENTS.local.md`.
+  Deeper extends/overrides broader; `.agents/` beats the plain file beside it, and
+  `.local` wins at its own level: it is the unshared override (machine- or
+  user-specific — either way, never committed or copied into a repo, plan, or shared
+  config). These files say what lives there and how to work in it, so reading them
+  first is cheaper than rediscovering it from the source. How `.agents/` is
+  populated — real directory, symlink, committed or not — is yours to decide.
+- **Global-config misses**: if these instructions caused a mistake or rework, or you
+  have an improvement idea, drop a note in `~/.agents/dotagents/findings/` and move on
+  — don't edit the config. Triage later folds them into `.../dotagents/DECISIONS.md`
+  and moves each (never deletes) to `.../findings/processed/`.
+- **This file**: everything between the `dotagents:begin`/`dotagents:end` markers is
+  managed — `dotagents init` refreshes it and leaves anything outside untouched. Add
+  your own rules and routing below the end marker, not inside.
+
+## Load on demand
+Read the matching file BEFORE such a task; skip it otherwise, never preemptively.
+Nothing ships here by default — add one routing line per file as you grow this
+config. A named agent with its own `~/.agents/<agent>.md` reads that too.
+<!-- dotagents:end -->

dotagents/_overlay/CLAUDE.md

@@ -0,0 +1,3 @@
+<!-- dotagents:begin -->
+@AGENTS.md
+<!-- dotagents:end -->

dotagents/_overlay/README.md

@@ -0,0 +1,41 @@
+# dotagents skeleton — understanding the hierarchy
+
+This is the minimal starter installed by `dotagents init`. It gives you the
+scaffolding to build your own agent config from scratch — it intentionally carries
+no opinionated flows, model-routing, or repo-standards content.
+
+## Layout
+
+- `AGENTS.md` — the root config, read by every agent session. Keep it lean: always-
+  on rules plus a "load on demand" routing list. Its content between the
+  `<!-- dotagents:begin -->` / `<!-- dotagents:end -->` markers is managed by
+  `dotagents init` — re-running `init` refreshes only that block, never touching
+  anything you add outside it.
+- `CLAUDE.md` (and any other per-agent entry file, e.g. `ANTIGRAVITY.md`) — a
+  one-liner (`@AGENTS.md`) that points that agent runner at the shared root config.
+  Add one per agent runner you use; they all converge on the same `AGENTS.md`.
+- `dotagents/DECISIONS.md` + `dotagents/decisions/` — a design log for this config
+  itself (why a rule exists, what changed and when), as a lean index + one file per
+  decision. Not loaded in normal sessions.
+- `dotagents/findings/` — where agents drop short notes when the config caused a
+  mistake or gap, instead of editing the config mid-task. `dotagents/findings/
+  processed/` is where triaged notes land (moved, never deleted) once folded into
+  `dotagents/DECISIONS.md`.
+
+## Growing your own config
+
+As you build out routines you want agents to follow repeatedly (planning, execution,
+code review, repo standards, language-specific conventions), put each in its own file
+under `~/.agents/` and add one routing line to `AGENTS.md`'s "Load on demand" list —
+loaded only when the task matches, never preemptively. This keeps every-session cost
+low regardless of how much topical detail accumulates. How you group those files is
+up to you; the overlays in this project happen to use `flows/` and `kb/`, but nothing
+in `dotagents` requires that layout.
+
+One filename *is* conventional: a named agent (Claude, Antigravity, …) reads its own
+`~/.agents/<agent>.md` on top of this file, so per-runner directives go there.
+
+If you'd rather start from a fuller, opinionated example than build from scratch, see
+this project's opt-in overlays (`engineering` rules, planning/execution flows, language
+knowledge bases, CI/reference templates) — layer them in deliberately with
+`dotagents install --overlays <path>`, never wholesale.

dotagents/_overlay/dotagents/DECISIONS.md

@@ -0,0 +1,20 @@
+# Config Design Decisions — index
+
+Not loaded in normal sessions. Read only when deliberately iterating on
+`~/.agents/AGENTS.md` or its flows.
+
+**How findings become config**: when an agent hits a mistake or gap caused by this
+config, it drops a short note in `~/.agents/dotagents/findings/` instead of editing the
+config mid-task. On request, triage that directory: fold each settled note into a
+decision below, then **move** (never delete) the processed file to
+`~/.agents/dotagents/findings/processed/`. This keeps the config's evolution auditable
+without letting routine work rewrite always-on rules under time pressure.
+
+**Structure** (mirrors the memory pattern — a lean index plus one file per entry, so a
+session reads this short index and opens only what it needs): each decision is its own
+file `decisions/D<nn>.md` with a one-line `description:` scan key; add one index line
+here per decision. Ships empty — this is your log to grow.
+
+## Decisions
+
+_(none yet)_

dotagents/_overlay/dotagents/cmds/README.md

@@ -0,0 +1,46 @@
+# `dotagents/cmds/` — your own commands go here
+
+`init` creates this directory in your store (`<store>/dotagents/cmds/`). Any
+`*.py` file you drop in it that defines a `duho` command class becomes a
+`dotagents <name>` subcommand — no registration, no config.
+
+```python
+# <store>/dotagents/cmds/hello.py
+from duho import Cmd, LoggingArgs
+
+
+class Hello(LoggingArgs, Cmd):
+    """Say hello."""
+
+    _parsername_ = "hello"
+
+    who: str = "world"
+    ("--who",)
+
+    def __call__(self) -> int:
+        print("hello, %s" % self.who)
+        return 0
+```
+
+Then `dotagents hello --who you`.
+
+Files whose name starts with `_` are skipped by discovery — use that prefix for
+shared helper modules.
+
+## Precedence
+
+Discovery layers sources so a later one overrides a same-named command:
+
+    built-ins  <  installed overlays' cmds/  <  system  <  user  <  project
+
+So a command you drop here (user scope) overrides one an overlay ships, and a
+project's `.agents/dotagents/cmds/` overrides yours.
+
+## dotagents itself ships none
+
+This directory is intentionally empty in a fresh install (D85). `link`/`sync`
+used to ship here; they are now `link-project`/`sync-project`, shipped by the
+opt-in **private-sync** overlay together with their logic — so plain dotagents
+carries no private-sync workflow. Install it with:
+
+    dotagents overlays add private-sync --source <overlays-checkout>