brigade-cli 0.5.0__py3-none-any.whl

brigade/ingest.py

@@ -0,0 +1,298 @@
+"""`brigade ingest` - route .claude/memory-handoffs/*.md into canonical memory.
+
+Conservative by design:
+  - auto-promote handoffs with safe card filenames + YAML frontmatter
+  - append-only routing for TOOLS.md, USER.md, rules/*.md, .learnings/*.md
+  - everything ambiguous lands in memory/handoff-inbox/ for manual review
+  - processed files move to .claude/memory-handoffs/processed/
+"""
+from __future__ import annotations
+
+import re
+import shutil
+import sys
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List
+
+SECTION_RE = re.compile(r"^##\s+(?P<name>.+?)\s*$", re.MULTILINE)
+SAFE_CARD_NAME_RE = re.compile(r"^[A-Za-z0-9._-]+\.md$")
+SAFE_RULE_PATH_RE = re.compile(r"^rules/[A-Za-z0-9._-]+\.md$")
+SAFE_SPECIAL_TARGETS = {
+    "TOOLS.md",
+    "USER.md",
+    ".learnings/LEARNINGS.md",
+    ".learnings/ERRORS.md",
+    ".learnings/FEATURE_REQUESTS.md",
+}
+
+# Writer harness id -> inbox dir (mirror of install._WRITER_INBOX).
+_WRITER_INBOXES = {
+    "claude": ".claude/memory-handoffs",
+    "codex": ".codex/memory-handoffs",
+}
+
+# Recognized handoff sections. Any section name outside this set is a signal
+# that the parser split content at an internal `##` heading; route to inbox.
+KNOWN_SECTIONS = {
+    "type",
+    "title",
+    "summary",
+    "durable facts",
+    "evidence",
+    "recommended memory action",
+    "target card",
+    "suggested card content",
+    "target document",
+    "suggested document content",
+}
+
+
+@dataclass
+class IngestStats:
+    processed: int = 0
+    promoted: int = 0
+    routed: int = 0
+    inboxed: int = 0
+    skipped: int = 0
+    actions: List[str] = field(default_factory=list)
+
+
+def _resolve_inbox_paths(target: Path) -> list[Path]:
+    """Return handoff inbox directories for `target` in deterministic order.
+
+    Reads `.brigade/config.json` when present and returns one inbox per
+    writer harness in the selection (alphabetical by harness id). Falls back
+    to the legacy `.claude/memory-handoffs/` path for pre-v0.3.0 installs.
+    """
+    from .config import load_config
+
+    cfg = load_config(target)
+    if cfg is None:
+        legacy = target / ".claude" / "memory-handoffs"
+        return [legacy] if legacy.is_dir() else []
+    paths: list[Path] = []
+    for h in sorted(cfg.selection.harnesses):
+        rel = _WRITER_INBOXES.get(h)
+        if rel and (target / rel).is_dir():
+            paths.append(target / rel)
+    return paths
+
+
+def run(
+    target: Path,
+    dry_run: bool = False,
+    promote_cards: bool = False,
+    route_documents: bool = False,
+) -> int:
+    """Process handoffs.
+
+    `promote_cards` and `route_documents` are opt-in. With neither flag,
+    every handoff routes to the review inbox so a human picks the action.
+    Match the cookbook wrapper by passing both flags explicitly.
+    """
+    target = target.expanduser().resolve()
+    inbox_dir = target / "memory" / "handoff-inbox"
+
+    handoff_dirs = _resolve_inbox_paths(target)
+    if not handoff_dirs:
+        legacy = target / ".claude" / "memory-handoffs"
+        print(f"brigade ingest: no handoff inbox at {legacy}", file=sys.stderr)
+        return 2
+
+    stats = IngestStats()
+
+    for handoffs_dir in handoff_dirs:
+        processed_dir = handoffs_dir / "processed"
+        for path in _list_handoffs(handoffs_dir):
+            stats.processed += 1
+            sections = parse(path)
+            outcome = decide(
+                sections,
+                target=target,
+                promote_cards=promote_cards,
+                route_documents=route_documents,
+            )
+            action = _execute(
+                outcome,
+                handoff_path=path,
+                target=target,
+                sections=sections,
+                inbox_dir=inbox_dir,
+                processed_dir=processed_dir,
+                dry_run=dry_run,
+            )
+            stats.actions.append(action.summary)
+            if action.kind == "promoted":
+                stats.promoted += 1
+            elif action.kind == "routed":
+                stats.routed += 1
+            elif action.kind == "inboxed":
+                stats.inboxed += 1
+            elif action.kind == "skipped":
+                stats.skipped += 1
+
+    _report(stats, dry_run=dry_run)
+    return 0
+
+
+def parse(path: Path) -> Dict[str, str]:
+    """Split a handoff into sections keyed by lowercased ## heading."""
+    body = path.read_text()
+    sections: Dict[str, str] = {}
+    last_name = None
+    last_pos = 0
+    for m in SECTION_RE.finditer(body):
+        if last_name is not None:
+            sections[last_name.lower()] = body[last_pos : m.start()].strip()
+        last_name = m.group("name")
+        last_pos = m.end()
+    if last_name is not None:
+        sections[last_name.lower()] = body[last_pos:].strip()
+    return sections
+
+
+@dataclass
+class Outcome:
+    kind: str  # promoted | routed | inboxed | skipped
+    dest: Path | None = None
+    reason: str = ""
+
+
+def decide(
+    sections: Dict[str, str],
+    target: Path,
+    promote_cards: bool,
+    route_documents: bool,
+) -> Outcome:
+    action = sections.get("recommended memory action", "").strip().lower()
+
+    stray = [s for s in sections if s not in KNOWN_SECTIONS]
+    if stray:
+        return Outcome(
+            "inboxed",
+            reason=f"unknown sections present (parser may have split content): {stray}",
+        )
+
+    if action in ("create-card", "update-card") and promote_cards:
+        card = sections.get("target card", "").strip()
+        content = sections.get("suggested card content", "")
+        if not SAFE_CARD_NAME_RE.match(card):
+            return Outcome("inboxed", reason=f"target card name unsafe: {card!r}")
+        if not content.lstrip().startswith("---"):
+            return Outcome("inboxed", reason="card content missing YAML frontmatter")
+        return Outcome("promoted", dest=target / "memory" / "cards" / card)
+
+    if action == "no-card" and route_documents:
+        document = sections.get("target document", "").strip()
+        content = sections.get("suggested document content", "")
+        if not document:
+            return Outcome("inboxed", reason="no-card handoff missing target document")
+        if not (document in SAFE_SPECIAL_TARGETS or SAFE_RULE_PATH_RE.match(document)):
+            return Outcome("inboxed", reason=f"target document not in safe list: {document!r}")
+        if not content.strip():
+            return Outcome("inboxed", reason="empty document content")
+        if "\n## " in ("\n" + content):
+            return Outcome(
+                "inboxed",
+                reason="document content contains `##` headings (would parse as new section)",
+            )
+        return Outcome("routed", dest=target / document)
+
+    if action == "":
+        return Outcome("inboxed", reason="missing `Recommended memory action`")
+    return Outcome("skipped", reason=f"action {action!r} not auto-handled")
+
+
+@dataclass
+class Action:
+    kind: str
+    summary: str
+
+
+def _execute(
+    outcome: Outcome,
+    handoff_path: Path,
+    target: Path,
+    sections: Dict[str, str],
+    inbox_dir: Path,
+    processed_dir: Path,
+    dry_run: bool,
+) -> Action:
+    name = handoff_path.name
+
+    if outcome.kind == "promoted":
+        dest = outcome.dest  # type: ignore[assignment]
+        assert dest is not None
+        content = sections.get("suggested card content", "").strip() + "\n"
+        summary = f"promote → {dest.relative_to(target)}  ({name})"
+        if not dry_run:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content)
+            _archive(handoff_path, processed_dir)
+        return Action("promoted", summary)
+
+    if outcome.kind == "routed":
+        dest = outcome.dest  # type: ignore[assignment]
+        assert dest is not None
+        content = sections.get("suggested document content", "").strip()
+        summary = f"append → {dest.relative_to(target)}  ({name})"
+        if not dry_run:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            with dest.open("a") as f:
+                f.write("\n\n" + content + "\n")
+            _archive(handoff_path, processed_dir)
+        return Action("routed", summary)
+
+    if outcome.kind in ("inboxed", "skipped"):
+        slug = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        dest = inbox_dir / f"{slug}-{handoff_path.stem}.md"
+        verb = "inbox" if outcome.kind == "inboxed" else "skip-inbox"
+        summary = f"{verb} → {dest.relative_to(target)}  ({name}; {outcome.reason})"
+        if not dry_run:
+            inbox_dir.mkdir(parents=True, exist_ok=True)
+            # Copy the original file verbatim so reviewers see what the
+            # harness actually wrote, not a reconstruction.
+            original = handoff_path.read_text()
+            header = (
+                f"<!-- routed from {handoff_path.name}\n"
+                f"     reason: {outcome.reason}\n"
+                f"     routed-at: {slug} -->\n\n"
+            )
+            dest.write_text(header + original)
+            _archive(handoff_path, processed_dir)
+        # Both inboxed and skipped are now archived; classify them uniformly.
+        return Action("inboxed", summary)
+
+    return Action("skipped", f"skip   {name}  ({outcome.reason})")
+
+
+def _list_handoffs(handoffs_dir: Path) -> List[Path]:
+    out: List[Path] = []
+    for p in sorted(handoffs_dir.iterdir()):
+        if p.is_file() and p.suffix == ".md" and p.name != "TEMPLATE.md":
+            out.append(p)
+    return out
+
+
+def _archive(src: Path, processed_dir: Path) -> None:
+    processed_dir.mkdir(parents=True, exist_ok=True)
+    dest = processed_dir / src.name
+    if dest.exists():
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+        dest = processed_dir / f"{src.stem}-{stamp}{src.suffix}"
+    shutil.move(str(src), dest)
+
+
+def _report(stats: IngestStats, dry_run: bool) -> None:
+    tag = "[dry-run] " if dry_run else ""
+    for line in stats.actions:
+        print(f"  {tag}{line}")
+    print()
+    print(
+        f"{tag}Processed {stats.processed}  Promoted {stats.promoted}  "
+        f"Routed {stats.routed}  Inboxed {stats.inboxed}  Skipped {stats.skipped}"
+    )
+    if stats.processed == 0:
+        print(f"{tag}NO_UPDATES")

brigade/install.py

@@ -0,0 +1,217 @@
+"""install_selection - the new install engine.
+
+Composes a depth manifest + N harness manifests + M include manifests
+into a single deduped file/dir list, then copies+renders into target.
+Persists the Selection to .brigade/config.json.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+from .config import Config, write_config
+from .selection import Selection
+from .templates import (
+    harness_memory_owner,
+    is_text,
+    load_depth_manifest,
+    load_harness_manifest,
+    load_include_manifest,
+    render,
+    template_root,
+)
+
+GITIGNORE_BEGIN = "# >>> brigade gitignore block >>>"
+GITIGNORE_END = "# <<< brigade gitignore block <<<"
+
+# Writer harness -> inbox-dir prefix. Only writer harnesses have an inbox.
+_WRITER_INBOX = {
+    "claude": ".claude/memory-handoffs",
+    "codex": ".codex/memory-handoffs",
+}
+
+
+def build_gitignore_block(selection: Selection) -> str:
+    lines = [
+        GITIGNORE_BEGIN,
+        "# Managed by `brigade init`. Edit between the markers to customize.",
+        "# Re-running `brigade init` replaces only the content between markers.",
+        "",
+    ]
+    for h in selection.harnesses:
+        inbox = _WRITER_INBOX.get(h)
+        if inbox:
+            lines.extend([
+                f"# {h}: handoffs are session-local and may contain private context.",
+                f"{inbox}/*",
+                f"!{inbox}/TEMPLATE.md",
+                f"!{inbox}/.gitkeep",
+                "",
+            ])
+    lines.extend([
+        "# Daily session logs are machine-local raw context.",
+        "memory/20[0-9][0-9]-[0-1][0-9]-[0-3][0-9].md",
+        "",
+        "# Review inbox: ambiguous handoffs awaiting human triage.",
+        "memory/handoff-inbox/",
+        "",
+        "# brigade local state (logs, scrub cache).",
+        ".brigade/logs/",
+        ".brigade/scrub-cache/",
+        GITIGNORE_END,
+        "",
+    ])
+    return "\n".join(lines)
+
+
+def apply_gitignore(target: Path, selection: Selection) -> str:
+    """Insert or replace the managed block in target's .gitignore. Returns 'created' or 'updated'."""
+    gi = target / ".gitignore"
+    block = build_gitignore_block(selection)
+    if not gi.exists():
+        gi.write_text(block)
+        return "created"
+    existing = gi.read_text()
+    if GITIGNORE_BEGIN in existing and GITIGNORE_END in existing:
+        prefix, _, rest = existing.partition(GITIGNORE_BEGIN)
+        _, _, suffix = rest.partition(GITIGNORE_END)
+        # Strip a trailing newline from prefix and a leading newline from suffix to avoid drift.
+        new_text = prefix.rstrip("\n") + ("\n\n" if prefix.strip() else "") + block + suffix.lstrip("\n")
+        gi.write_text(new_text)
+        return "updated"
+    sep = "" if existing.endswith("\n") else "\n"
+    gi.write_text(existing + sep + "\n" + block)
+    return "updated"
+
+
+def resolve_manifests(selection: Selection) -> Tuple[List[dict], List[str], List[str]]:
+    """Return (files, dirs, post_install_notes) for a Selection.
+
+    Files are deduped by `dst`: later manifests win, so a harness can
+    override a depth-baseline file by referencing the same dst.
+    """
+    files: List[dict] = []
+    dirs: List[str] = []
+    notes: List[str] = []
+
+    depth_manifest = load_depth_manifest(selection.depth)
+    files.extend(depth_manifest.get("files", []))
+    dirs.extend(depth_manifest.get("dirs", []))
+    notes.extend(depth_manifest.get("post_install_notes", []))
+
+    for harness_id in selection.harnesses:
+        m = load_harness_manifest(harness_id)
+        files.extend(m.get("files", []))
+        dirs.extend(m.get("dirs", []))
+        notes.extend(m.get("post_install_notes", []))
+
+    for include_id in selection.includes:
+        m = load_include_manifest(include_id)
+        files.extend(m.get("files", []))
+        dirs.extend(m.get("dirs", []))
+        notes.extend(m.get("post_install_notes", []))
+
+    # Dedupe files by dst (last-wins).
+    seen: dict[str, dict] = {}
+    for entry in files:
+        seen[entry["dst"]] = entry
+    deduped_files = list(seen.values())
+    deduped_dirs = sorted(set(dirs))
+
+    return deduped_files, deduped_dirs, notes
+
+
+def install_selection(
+    target: Path,
+    selection: Selection,
+    force: bool = False,
+    dry_run: bool = False,
+    allow_home: bool = False,
+) -> int:
+    """Install a Selection into `target`. Returns process exit code."""
+    selection.validate()
+    target = target.expanduser().resolve()
+
+    if target == Path.home() and not allow_home:
+        print(
+            f"error: refusing to install directly into $HOME ({target}).",
+            file=sys.stderr,
+        )
+        return 5
+
+    files, dirs, notes = resolve_manifests(selection)
+
+    if dry_run:
+        print(f"[dry-run] target: {target}")
+        print(f"[dry-run] depth: {selection.depth}")
+        print(f"[dry-run] harnesses: {','.join(selection.harnesses) or '(none)'}")
+        print(f"[dry-run] owner: {selection.owner}")
+        print(f"[dry-run] includes: {','.join(selection.includes) or '(none)'}")
+        print(f"[dry-run] would create {len(dirs)} dir(s) and {len(files)} file(s)")
+        for d in dirs:
+            print(f"  dir   {target / d}")
+        for entry in files:
+            print(f"  file  {target / entry['dst']}")
+        return 0
+
+    target.mkdir(parents=True, exist_ok=True)
+
+    if not force:
+        conflicts = [target / f["dst"] for f in files if (target / f["dst"]).exists()]
+        if conflicts:
+            print("error: refusing to overwrite existing files (use --force):", file=sys.stderr)
+            for c in conflicts:
+                print(f"  {c}", file=sys.stderr)
+            return 3
+
+    for d in dirs:
+        (target / d).mkdir(parents=True, exist_ok=True)
+
+    owner_label = harness_memory_owner(selection.owner, selection.owner)
+    context = {
+        "memory_owner": selection.owner,
+        "memory_owner_name": owner_label,
+        "harness": selection.owner,
+    }
+
+    root = template_root()
+    for entry in files:
+        src = root / entry["src"]
+        dst = target / entry["dst"]
+        if not src.is_file():
+            print(f"error: template missing: {src}", file=sys.stderr)
+            return 4
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if is_text(entry["src"]):
+            dst.write_text(render(src.read_text(), context))
+        else:
+            shutil.copyfile(src, dst)
+        mode_str = entry.get("mode")
+        if mode_str:
+            os.chmod(dst, int(mode_str, 8))
+
+    # Persist config.json.
+    write_config(target, Config(version=1, selection=selection))
+
+    result = apply_gitignore(target, selection)
+    print(f"brigade: gitignore {result}")
+
+    # Post-install output.
+    print(f"brigade: installed depth={selection.depth} harnesses={','.join(selection.harnesses) or '(none)'} -> {target}")
+    print(f"brigade: memory owner -> {owner_label}")
+    if "hermes" in selection.harnesses:
+        print(
+            "brigade: NOTE - the hermes adapter is experimental. "
+            "Validate against your real Hermes install before relying on it. "
+            "See CONTRIBUTING.md for graduation criteria.",
+            file=sys.stderr,
+        )
+    if notes:
+        print()
+        print("Next steps:")
+        for note in notes:
+            print(f"  - {note}")
+    return 0

brigade/prompt.py

@@ -0,0 +1,135 @@
+"""Hand-rolled interactive prompt for harness/depth/include selection.
+
+No external deps. Uses stdin line input + numbered toggles, so it works
+over any TTY (no raw mode, no curses, no ANSI escape sequences required).
+"""
+from __future__ import annotations
+
+import sys
+from typing import List
+
+from .selection import (
+    KNOWN_HARNESSES,
+    KNOWN_DEPTHS,
+    KNOWN_INCLUDES,
+    Selection,
+    resolve_owner,
+)
+
+
+class NonInteractiveError(Exception):
+    """Raised when prompt_for_selection() runs without a TTY."""
+
+
+_HARNESS_ORDER = ["claude", "codex", "openclaw", "hermes"]
+_DEPTH_ORDER = ["repo", "workspace"]
+_INCLUDE_ORDER = ["publisher"]
+
+_HARNESS_LABELS = {
+    "claude": "Claude Code",
+    "codex": "Codex",
+    "openclaw": "OpenClaw",
+    "hermes": "Hermes (experimental)",
+}
+
+_DEPTH_LABELS = {
+    "repo": "repo       (handoff flow + publish guard)",
+    "workspace": "workspace  (full home: MEMORY.md, TOOLS.md, USER.md, ...)",
+}
+
+_INCLUDE_LABELS = {
+    "publisher": "publisher  (content-guard policies for blog/social/docs)",
+}
+
+
+def prompt_for_selection() -> Selection:
+    if not sys.stdin.isatty():
+        raise NonInteractiveError(
+            "brigade init needs a TTY for the interactive prompt. "
+            "Pass --depth and --harnesses for scripting."
+        )
+
+    selected_harnesses = _toggle_prompt(
+        title="Which harnesses do you use?",
+        options=_HARNESS_ORDER,
+        labels=_HARNESS_LABELS,
+        defaults=["claude"],
+    )
+    depth = _single_prompt(
+        title="Depth?",
+        options=_DEPTH_ORDER,
+        labels=_DEPTH_LABELS,
+        default="repo",
+    )
+    selected_includes = _toggle_prompt(
+        title="Add-ons?",
+        options=_INCLUDE_ORDER,
+        labels=_INCLUDE_LABELS,
+        defaults=[],
+    )
+
+    owner = resolve_owner(selected_harnesses)
+    return Selection(
+        depth=depth,
+        harnesses=selected_harnesses,
+        owner=owner,
+        includes=selected_includes,
+    )
+
+
+def _toggle_prompt(title, options, labels, defaults):
+    selected = list(defaults)
+    print()
+    print(title + " (type numbers separated by space/comma to toggle, enter to confirm)")
+    while True:
+        for i, opt in enumerate(options, start=1):
+            mark = "x" if opt in selected else " "
+            print(f"  [{mark}] {i}. {labels.get(opt, opt)}")
+        raw = sys.stdin.readline()
+        if raw == "":  # EOF
+            break
+        raw = raw.strip()
+        if not raw:
+            break
+        tokens = [t.strip() for t in raw.replace(",", " ").split() if t.strip()]
+        invalid = []
+        for t in tokens:
+            try:
+                idx = int(t)
+            except ValueError:
+                invalid.append(t)
+                continue
+            if not 1 <= idx <= len(options):
+                invalid.append(t)
+                continue
+            opt = options[idx - 1]
+            if opt in selected:
+                selected.remove(opt)
+            else:
+                selected.append(opt)
+        if invalid:
+            print(f"  (ignored invalid: {' '.join(invalid)})")
+    # Preserve canonical order rather than toggle order.
+    return [o for o in options if o in selected]
+
+
+def _single_prompt(title, options, labels, default):
+    print()
+    print(title + " (type a number, enter for default)")
+    for i, opt in enumerate(options, start=1):
+        marker = "*" if opt == default else " "
+        print(f"  {marker} {i}. {labels.get(opt, opt)}")
+    raw = sys.stdin.readline()
+    if raw == "":
+        return default
+    raw = raw.strip()
+    if not raw:
+        return default
+    try:
+        idx = int(raw)
+        if 1 <= idx <= len(options):
+            return options[idx - 1]
+    except ValueError:
+        pass
+    print(f"  (invalid; using default {default!r})")
+    return default