@andespindola/crow-skills 0.3.0 → 0.5.0

package/crow_skills/integrations.py

@@ -0,0 +1,520 @@
+"""Host UI integrations that show the active crow-behaviour run.
+
+Each integration uses an extension point the host really exposes and that was
+checked on the host versions listed in docs/cli.md:
+
+- claude-statusline: the ``statusLine`` command in ~/.claude/settings.json. A
+  status line that already exists is chained (it keeps printing first), never
+  replaced.
+- codex-statusline: ``[tui].status_line`` in ~/.codex/config.toml, which only
+  accepts Codex's built-in items. It shows Codex's own plan progress
+  ("task-progress") and token usage; it cannot run a command. Applied only
+  when the user has not set a status line.
+- tmux-status: a segment appended to ``status-right`` from a sourced snippet,
+  for every agent, only when tmux is installed and already configured.
+
+Gemini CLI (footer takes built-in items only), Antigravity (no status/footer
+setting) and Devin CLI (no status line) have no surface that can display an
+external value; they get the tmux segment and ``crow-skills progress``.
+
+Ownership: one key (claude), one marked block (codex, tmux.conf) and two whole
+files under ~/.config/crow-skills and the CLI state. Every edited file is
+backed up first, written atomically, never through a symlink or hard link,
+and restored on uninstall only if it still holds what this CLI wrote. These
+are best-effort steps after the skills transaction: a refusal is reported in
+``skipped`` and never undoes the skills.
+"""
+from contextlib import nullcontext
+from copy import deepcopy
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import sys
+
+from .guide import protect, read_regular, sha, tomllib, write_atomic
+from .source import CrowError
+from .storage import atomic_json, checked, private_dir, read_json
+
+NAMES = ("claude-statusline", "codex-statusline", "tmux-status")
+OWNERS = {"claude-statusline": ("claude",), "codex-statusline": ("codex",),
+          "tmux-status": ("claude", "codex", "gemini", "devin")}
+BEGIN = "# >>> crow-skills integrations (gerenciado; use crow-skills integrations uninstall) >>>"
+END = "# <<< crow-skills integrations <<<"
+CODEX_ITEMS = ["model-with-reasoning", "context-remaining", "current-dir", "task-progress", "used-tokens"]
+SNIPPET_HEADER = "# Gerenciado por crow-skills (integração tmux). Não edite; use crow-skills integrations."
+UNSUPPORTED = {
+    "gemini": ("Agente gemini do instalador = Antigravity (agy): sem status line nem rodapé configurável; no ledger use host agy, "
+               "nunca gemini (gemini é o Gemini CLI, cujo rodapé ui.footer.items só aceita itens nativos). "
+               "Use o segmento tmux ou crow-skills progress."),
+    "devin": "Devin CLI não tem status line nem rodapé configurável; use o segmento tmux ou crow-skills progress.",
+}
+
+
+def tmux_binary():
+    return shutil.which("tmux")
+
+
+def python_binary():
+    return shutil.which("python3") or sys.executable
+
+
+def now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def root(store):
+    return store.root / "integrations"
+
+
+def state_path(store):
+    return root(store) / "state.json"
+
+
+def load_state(store):
+    path = checked(state_path(store))
+    if not path.exists():
+        return {"schema_version": 1, "integrations": {}}
+    data = read_json(path)
+    if data.get("schema_version") != 1 or not isinstance(data.get("integrations"), dict):
+        raise CrowError("invalid_state", "Estado de integrações inválido; nada alterado.")
+    return data
+
+
+def script_path(store):
+    return root(store) / "crow_progress.py"
+
+
+def script_source():
+    return (Path(__file__).resolve().parent / "progress.py").read_bytes()
+
+
+def quoted_ok(*paths):
+    return all(not re.search(r"[\"'\\$`\n]", str(p)) for p in paths)
+
+
+def backup(store, name, data):
+    if data is None:
+        return None
+    directory = private_dir(root(store) / "backups")
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    path = directory / (stamp + "-" + name + ".bak")
+    write_atomic(path, data, 0o600)
+    return path.name
+
+
+def restore_bytes(store, record, path, old):
+    """Original bytes from the install backup, when the file still holds exactly what we wrote."""
+    name = record.get("backup")
+    if old is None or not name or record.get("written_sha") != sha(old) or "/" in name:
+        return None
+    try:
+        return read_regular(checked(root(store) / "backups" / name))
+    except (CrowError, OSError):
+        return None
+
+
+def write(path, data, old):
+    mode = (path.lstat().st_mode & 0o777) if old is not None else 0o644
+    if not path.parent.exists():
+        path.parent.mkdir(parents=True, mode=0o755)
+    write_atomic(path, data, mode)
+
+
+# --- claude ---------------------------------------------------------------------------------
+
+def claude_sync(store, home, record, desired, python, dry):
+    path = protect(home / ".claude" / "settings.json", home)
+    old = read_regular(path)
+    try:
+        settings = json.loads(old.decode("utf-8")) if old is not None and old.strip() else {}
+    except (UnicodeDecodeError, ValueError):
+        return None, "skip", "~/.claude/settings.json não é JSON válido; nada alterado."
+    if not isinstance(settings, dict):
+        return None, "skip", "~/.claude/settings.json não é um objeto JSON; nada alterado."
+    current = settings.get("statusLine")
+    chain_file = root(store) / "claude-statusline-chain.json"
+    if not desired:
+        if not record:
+            return None, "unchanged", None
+        if current != record["value"]:
+            if not dry and chain_file.exists():
+                chain_file.unlink()
+            return None, "skip", "statusLine foi alterado depois da instalação; mantido como está e removido do controle do crow-skills."
+        if record.get("previous") is not None:
+            settings["statusLine"] = record["previous"]
+        else:
+            settings.pop("statusLine", None)
+        if dry:
+            return None, "remove", None
+        original = None if record.get("created_file") else restore_bytes(store, record, path, old)
+        backup(store, "claude-settings", old)
+        if record.get("created_file") and not settings:
+            path.unlink()
+        elif original is not None:
+            # Nothing else changed since the install: give the file back byte for byte.
+            write(path, original, old)
+        else:
+            write(path, (json.dumps(settings, ensure_ascii=False, indent=2) + "\n").encode("utf-8"), old)
+        if chain_file.exists():
+            chain_file.unlink()
+        return None, "remove", None
+    script = script_path(store)
+    if not quoted_ok(python, script, chain_file):
+        return record, "skip", "Caminho do Python ou do estado contém aspas/variáveis; status line não configurada."
+    previous = record.get("previous") if record else None
+    if record and current != record["value"]:
+        return record, "skip", "statusLine foi alterado depois da instalação; não sobrescrito. Rode crow-skills integrations uninstall para desfazer o controle."
+    if not record and current is not None:
+        if not (isinstance(current, dict) and current.get("type") == "command" and isinstance(current.get("command"), str)):
+            return None, "skip", "statusLine existente não é do tipo command; não encadeado nem substituído."
+        previous = current
+    command = shlex.quote(str(python)) + " " + shlex.quote(str(script)) + " statusline"
+    if previous is not None:
+        command += " --chain-file " + shlex.quote(str(chain_file))
+    # A chained status line keeps its own keys (padding and any other); only the command changes.
+    value = {k: v for k, v in previous.items() if k not in ("type", "command")} if previous is not None else {"padding": 0}
+    value = {"type": "command", "command": command, **value}
+    if record and current == value:
+        return record, "unchanged", None
+    settings["statusLine"] = value
+    action = "update" if record else ("chain" if previous is not None else "install")
+    new_record = {"path": str(path), "value": value, "previous": previous, "installed_at": now(),
+                  "created_file": record.get("created_file", False) if record else old is None}
+    if dry:
+        return new_record, action, None
+    if previous is not None:
+        atomic_json(chain_file, {"command": previous["command"]})
+    safety = backup(store, "claude-settings", old)
+    # The restore point is the pre-install backup. An update keeps it only while the file
+    # still holds exactly what this CLI wrote; otherwise uninstall restores the key only.
+    if record:
+        new_record["backup"] = record.get("backup") if record.get("written_sha") == sha(old or b"") else None
+    else:
+        new_record["backup"] = safety
+    data = (json.dumps(settings, ensure_ascii=False, indent=2) + "\n").encode("utf-8")
+    write(path, data, old)
+    new_record["written_sha"] = sha(data)
+    return new_record, action, None
+
+
+# --- codex ---------------------------------------------------------------------------------
+
+def marked(text):
+    begins = [m.start() for m in re.finditer(r"(?m)^" + re.escape(BEGIN) + r"\n", text)]
+    ends = [m.end() for m in re.finditer(r"(?m)^" + re.escape(END) + r"\n", text)]
+    if not begins and not ends:
+        return None
+    if len(begins) != 1 or len(ends) != 1 or ends[0] <= begins[0]:
+        raise CrowError("integration_corrupted", "Marcadores de integração crow-skills incompletos ou duplicados; revise manualmente.")
+    return begins[0], ends[0]
+
+
+def codex_block(created_table):
+    items = "status_line = [" + ", ".join('"' + i + '"' for i in CODEX_ITEMS) + "]\n"
+    return BEGIN + "\n" + ("[tui]\n" if created_table else "") + items + END + "\n"
+
+
+def codex_removal(text, span, record):
+    """Text without the managed block, or None when removing it would change anything else.
+
+    The block must be exactly what install wrote, and the parsed result must
+    equal the current parse minus tui.status_line (minus an emptied [tui]
+    that install created). When install created [tui] and keys were added
+    below the block since, the header stays so they keep their table.
+    """
+    created_table = record.get("created_table", False)
+    if text[span[0]:span[1]] != codex_block(created_table):
+        return None
+    try:
+        current = tomllib.loads(text)
+    except tomllib.TOMLDecodeError:
+        return None
+    expected = deepcopy(current)
+    tui = expected.get("tui")
+    if not isinstance(tui, dict) or tui.get("status_line") != CODEX_ITEMS:
+        return None
+    del tui["status_line"]
+    attempts = []
+    if created_table and not tui:
+        del expected["tui"]
+        rest = text[:span[0]] + text[span[1]:]
+        if record.get("added_newline") and rest.endswith("\n") and span[1] == len(text):
+            rest = rest[:-1]
+        attempts.append(rest)
+    elif created_table:
+        attempts.append(text[:span[0]] + "[tui]\n" + text[span[1]:])
+    else:
+        attempts.append(text[:span[0]] + text[span[1]:])
+    for result in attempts:
+        try:
+            if tomllib.loads(result) == expected:
+                return result
+        except tomllib.TOMLDecodeError:
+            continue
+    return None
+
+
+def codex_sync(store, home, record, desired, python, dry):
+    del python
+    if tomllib is None:
+        return record, "skip", "Python 3.11+ (tomllib) é necessário para editar config.toml com verificação."
+    directory = home / ".codex"
+    if not directory.is_dir():
+        return record, "skip", "Codex sem ~/.codex; nada alterado."
+    path = protect(directory / "config.toml", home)
+    old = read_regular(path)
+    try:
+        text = old.decode("utf-8") if old is not None else ""
+    except UnicodeDecodeError:
+        return record, "skip", "config.toml não é UTF-8; nada alterado."
+    span = marked(text)
+    stripped = text[:span[0]] + text[span[1]:] if span else text
+    try:
+        base = tomllib.loads(stripped)
+    except tomllib.TOMLDecodeError:
+        return record, "skip", "config.toml não é TOML válido; nada alterado."
+    if not desired:
+        if not record:
+            return None, "unchanged", None
+        if not span:
+            return None, "skip", "Bloco de integração ausente em config.toml; nada a remover."
+        result = codex_removal(text, span, record)
+        if result is None:
+            return None, "skip", ("Bloco do crow-skills em config.toml foi editado ou a remoção mudaria outras chaves "
+                                  "(por exemplo, chaves acrescentadas a [tui] depois do bloco); nada alterado, "
+                                  "remova o bloco manualmente e o controle do crow-skills foi encerrado.")
+        if dry:
+            return None, "remove", None
+        backup(store, "codex-config", old)
+        if record.get("created_file") and not result.strip():
+            path.unlink()
+        else:
+            write(path, result.encode("utf-8"), old)
+        return None, "remove", None
+    tui = base.get("tui")
+    added_newline = record.get("added_newline", False) if record else False
+    if span and record:
+        current_block = text[span[0]:span[1]]
+        created_table = record.get("created_table", False)
+        block = codex_block(created_table)
+        if current_block == block:
+            return record, "unchanged", None
+        result = text[:span[0]] + block + text[span[1]:]
+    elif span:
+        return record, "skip", "Bloco de integração sem registro no estado; revise config.toml manualmente."
+    elif tui is None:
+        created_table = True
+        block = codex_block(True)
+        added_newline = bool(stripped) and not stripped.endswith("\n")
+        result = stripped + ("\n" if added_newline else "") + block
+    elif isinstance(tui, dict) and "status_line" not in tui:
+        headers = list(re.finditer(r"(?m)^\[tui\][ \t]*(?:#.*)?\n", stripped))
+        if len(headers) != 1:
+            return None, "skip", "Tabela [tui] definida de forma não editável com segurança; status line não alterada."
+        created_table = False
+        block = codex_block(False)
+        cut = headers[0].end()
+        result = stripped[:cut] + block + stripped[cut:]
+    else:
+        return None, "skip", "tui.status_line já definido pelo usuário; não sobrescrito."
+    expected = deepcopy(base)
+    expected.setdefault("tui", {})["status_line"] = CODEX_ITEMS
+    try:
+        if tomllib.loads(result) != expected:
+            raise ValueError("diff")
+    except (tomllib.TOMLDecodeError, ValueError):
+        return record, "skip", "A edição do config.toml não preservaria o restante do arquivo; nada alterado."
+    action = "update" if record else "install"
+    new_record = {"path": str(path), "created_table": created_table, "added_newline": added_newline, "installed_at": now(),
+                  "created_file": record.get("created_file", False) if record else old is None}
+    if dry:
+        return new_record, action, None
+    new_record["backup"] = backup(store, "codex-config", old)
+    write(path, result.encode("utf-8"), old)
+    return new_record, action, None
+
+
+# --- tmux --------------------------------------------------------------------------------------
+
+def tmux_conf(home):
+    candidates = [home / ".tmux.conf"]
+    xdg = os.environ.get("XDG_CONFIG_HOME") if home == Path.home().resolve() else None
+    candidates.append((Path(xdg).expanduser() if xdg else home / ".config") / "tmux" / "tmux.conf")
+    for candidate in candidates:
+        if os.path.lexists(candidate):
+            return Path(os.path.abspath(candidate))
+    return None
+
+
+def snippet_path(home):
+    return home / ".config" / "crow-skills" / "tmux.conf"
+
+
+def snippet_content(python, script):
+    # #{q:...} makes tmux shell-escape the pane path: a directory named with $(...) or
+    # backticks must reach the script as data, never run. python/script are checked by
+    # quoted_ok (no quotes, $, backticks or backslashes) before this is written.
+    command = '"' + str(python) + '" "' + str(script) + '" tmux --cwd #{q:pane_current_path}'
+    # Guard on status-right itself, not on a server option: a reload of the user's
+    # tmux.conf resets status-right, and the segment must come back after it.
+    return (SNIPPET_HEADER + "\n"
+            "if-shell -F '#{m:*" + script.name + "*,#{status-right}}' '' {\n"
+            "  set -ag status-right ' #(" + command + ")'\n"
+            "}\n")
+
+
+def symlinked(path):
+    path = Path(os.path.abspath(path))
+    return any(p.is_symlink() for p in (path, *path.parents))
+
+
+def tmux_sync(store, home, record, desired, python, dry):
+    snippet = snippet_path(home)
+    if not desired:
+        if not record:
+            return None, "unchanged", None
+        if dry:
+            return None, "remove", None
+        notes = []
+        conf = Path(record["conf"]) if record.get("conf") else None
+        if conf and record.get("block"):
+            if symlinked(conf):
+                notes.append("tmux.conf virou symlink; bloco não removido.")
+            else:
+                old = read_regular(conf)
+                text = old.decode("utf-8", "replace") if old is not None else ""
+                span = marked(text) if old is not None else None
+                if span:
+                    rest = text[:span[0]] + text[span[1]:]
+                    if record.get("added_newline") and rest.endswith("\n"):
+                        rest = rest[:-1]
+                    backup(store, "tmux-conf", old)
+                    write(conf, rest.encode("utf-8"), old)
+        if os.path.lexists(snippet) and not symlinked(snippet):
+            data = read_regular(snippet)
+            if data is not None and data.decode("utf-8", "replace").startswith(SNIPPET_HEADER):
+                snippet.unlink()
+                try:
+                    snippet.parent.rmdir()
+                except OSError:
+                    pass
+        notes.append("O segmento sai da sessão atual quando o status-right é redefinido (tmux source-file de um tmux.conf que o define) "
+                     "ou quando o servidor tmux reinicia.")
+        return None, "remove", " ".join(notes)
+    if not tmux_binary():
+        return record, "skip", "tmux não encontrado no PATH; segmento não instalado."
+    conf = tmux_conf(home)
+    if conf is None:
+        return record, "skip", "tmux sem arquivo de configuração (~/.tmux.conf ou ~/.config/tmux/tmux.conf); nada alterado."
+    script = script_path(store)
+    if not quoted_ok(python, script, snippet):
+        return record, "skip", "Caminho do Python ou do estado contém aspas/variáveis; segmento não instalado."
+    content = snippet_content(python, script).encode("utf-8")
+    line = "source-file -q '" + str(snippet) + "'"
+    block = BEGIN + "\n" + line + "\n" + END + "\n"
+    if symlinked(snippet):
+        return record, "skip", "~/.config/crow-skills é symlink; segmento não instalado."
+    manual = symlinked(conf)
+    old = None if manual else read_regular(conf)
+    text = old.decode("utf-8", "replace") if old is not None else ""
+    span = marked(text) if old is not None else None
+    current_snippet = read_regular(snippet) if os.path.lexists(snippet) else None
+    if current_snippet is not None and not current_snippet.decode("utf-8", "replace").startswith(SNIPPET_HEADER):
+        return record, "skip", str(snippet) + " existe e não é gerenciado; nada alterado."
+    in_place = manual or (span is not None and text[span[0]:span[1]] == block)
+    if record and in_place and current_snippet == content:
+        return record, "unchanged", ("tmux.conf é symlink: adicione manualmente a linha " + line) if manual else None
+    action = "update" if record else "install"
+    new_record = {"conf": str(conf), "snippet": str(snippet), "block": not manual, "installed_at": now(),
+                  "added_newline": record.get("added_newline", False) if record else False}
+    note = None
+    if manual:
+        note = "tmux.conf é symlink (não é gravado através de links); snippet instalado. Adicione ao seu tmux.conf: " + line
+    if dry:
+        return new_record, action, note
+    write(snippet, content, current_snippet)
+    if not manual and not (span and text[span[0]:span[1]] == block):
+        if span:
+            result = text[:span[0]] + block + text[span[1]:]
+        else:
+            new_record["added_newline"] = bool(text) and not text.endswith("\n")
+            result = text + ("\n" if new_record["added_newline"] else "") + block
+        new_record["backup"] = backup(store, "tmux-conf", old)
+        write(conf, result.encode("utf-8"), old)
+    return new_record, action, note
+
+
+SYNC = {"claude-statusline": claude_sync, "codex-statusline": codex_sync, "tmux-status": tmux_sync}
+
+
+# --- orchestration -------------------------------------------------------------------------
+
+def sync(store, home, wanted, dry_run=False, python=None):
+    """Bring every integration in line with the agents that have crow-behaviour.
+
+    wanted: agents that will have crow-behaviour managed after the command.
+    Returns a report; never raises for a single integration's refusal.
+    """
+    python = python or python_binary()
+    report = {"changes": [], "skipped": [], "unsupported": [{"agent": a, "reason": r} for a, r in UNSUPPORTED.items() if a in wanted]}
+    try:
+        state = load_state(store)
+    except CrowError as exc:
+        report["skipped"].append({"integration": "*", "reason": str(exc)})
+        return report
+    after = {"schema_version": 1, "integrations": dict(state["integrations"])}
+    with (nullcontext() if dry_run else store.lock()):
+        if not dry_run and any(set(OWNERS[n]) & set(wanted) for n in NAMES):
+            script = script_path(store)
+            private_dir(root(store))
+            source = script_source()
+            if not script.exists() or sha(script.read_bytes()) != sha(source):
+                write_atomic(checked(script), source, 0o644)
+        for name in NAMES:
+            desired = bool(set(OWNERS[name]) & set(wanted))
+            record = state["integrations"].get(name)
+            try:
+                new_record, action, note = SYNC[name](store, home, record, desired, python, dry_run)
+            except (CrowError, OSError, ValueError) as exc:
+                report["skipped"].append({"integration": name, "reason": str(exc) or "falha de leitura/gravação"})
+                continue
+            if action == "skip":
+                report["skipped"].append({"integration": name, "reason": note})
+            elif action != "unchanged" or note:
+                change = {"integration": name, "action": action}
+                if note:
+                    change["note"] = note
+                report["changes"].append(change)
+            if new_record is None:
+                after["integrations"].pop(name, None)
+            else:
+                after["integrations"][name] = new_record
+        if not dry_run:
+            if after != state:
+                atomic_json(state_path(store), after)
+            if not after["integrations"]:
+                script = script_path(store)
+                if script.exists():
+                    script.unlink()
+    report["dry_run"] = dry_run
+    return report
+
+
+def status(store, home):
+    state = load_state(store)
+    rows = []
+    for name in NAMES:
+        record = state["integrations"].get(name)
+        row = {"integration": name, "agents": list(OWNERS[name]), "status": "installed" if record else "absent"}
+        if record:
+            row["path"] = record.get("path") or record.get("conf")
+            if name == "tmux-status" and not record.get("block"):
+                row["note"] = "tmux.conf é symlink; linha source-file adicionada manualmente pelo usuário."
+        rows.append(row)
+    for agent, reason in UNSUPPORTED.items():
+        rows.append({"integration": agent + "-statusline", "agents": [agent], "status": "unsupported", "note": reason})
+    return rows