@andespindola/crow-skills 0.1.0

package/crow_skills/cli.py

@@ -0,0 +1,241 @@
+"""Human and agent CLI. Noninteractive mutations require explicit --yes."""
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from . import __version__
+from .agents import AGENTS, destinations, inventory
+from .source import CrowError, Source, valid_name
+from .storage import Store, checked
+
+DEFAULT_SOURCE = Path(__file__).resolve().parents[1]
+MUTATIONS = {"install", "update", "uninstall", "rollback", "recover"}
+
+
+class Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise CrowError("usage", message)
+
+
+def parser():
+    common = Parser(add_help=False)
+    for flag, kwargs in [
+        ("--source", {"help": "Clone Git existente (padrão: checkout do CLI)"}),
+        ("--ref", {"help": "Commit/tag/ref da fonte; padrão HEAD, sem checkout"}),
+        ("--home", {"help": "Perfil local alternativo, para ambientes isolados"}),
+        ("--agents", {"help": "Agentes separados por vírgula: " + ",".join(AGENTS)}),
+        ("--global", {"dest": "global_scope", "action": "store_true", "help": "Escopo do usuário"}),
+        ("--project", {"help": "Diretório físico do projeto"}),
+        ("--dest", {"help": "Diretório de skills explícito, para outro host"}),
+        ("--json", {"action": "store_true", "help": "Envelope JSON; nunca abre prompts"}),
+        ("--non-interactive", {"action": "store_true"}),
+        ("--yes", {"action": "store_true", "help": "Aplicar o escopo explícito sem prompt"}),
+        ("--dry-run", {"action": "store_true", "help": "Preview sem gravar estado ou instalar"}),
+        ("--fetch", {"action": "store_true", "help": "Buscar origin explicitamente; não cria clone"}),
+    ]:
+        common.add_argument(flag, default=argparse.SUPPRESS, **kwargs)
+    p = Parser(prog="crow-skills", parents=[common], description="Instale pacotes crow completos, por agente e revisão, sem executar scripts de skills.")
+    p.add_argument("--version", action="store_true")
+    sub = p.add_subparsers(dest="command")
+    for name in ("list", "agents", "status", "doctor"):
+        sub.add_parser(name, parents=[common])
+    for name in ("info", "related"):
+        child = sub.add_parser(name, parents=[common])
+        child.add_argument("name")
+    for name in ("install", "update", "uninstall"):
+        child = sub.add_parser(name, parents=[common])
+        child.add_argument("skills", nargs="*")
+        child.add_argument("--all", action="store_true", help="Todos do catálogo (install) ou gerenciados (update/uninstall)")
+        if name != "uninstall":
+            child.add_argument("--replace", action="store_true", help="Autorizar substituição com backup de pacote não gerenciado")
+            child.add_argument("--with-handoffs", action="store_true", help="Incluir apenas handoffs diretos opcionais do catálogo")
+        child.add_argument("--overwrite-modified", action="store_true", help="Autorizar backup e substituição/remoção de edições locais")
+    for name in ("rollback", "recover"):
+        child = sub.add_parser(name, parents=[common])
+        child.add_argument("--transaction", required=name == "rollback")
+    return p
+
+
+def prompt(text):
+    print(text, file=sys.stderr, end=" ", flush=True)
+    line = sys.stdin.readline()
+    if not line:
+        raise CrowError("cancelled", "Entrada encerrada; nenhuma instalação autorizada.")
+    return line.strip()
+
+
+def terminal(text):
+    """Do not render terminal escapes or invisible bidi controls from metadata."""
+    return "".join(c if c.isprintable() or c in "\n\t" else c.encode("unicode_escape").decode("ascii") for c in str(text))
+
+
+def scope(args, home, interactive=False, read=False):
+    if sum(bool(getattr(args, k, None)) for k in ("global_scope", "project", "dest")) > 1:
+        raise CrowError("usage", "Escolha somente um de --global, --project ou --dest.")
+    agents = getattr(args, "agents", None)
+    project = getattr(args, "project", None)
+    custom = getattr(args, "dest", None)
+    if not read and not any(getattr(args, k, None) for k in ("global_scope", "project", "dest")):
+        if not interactive:
+            raise CrowError("usage", "Mutações exigem escopo explícito: --global, --project PATH ou --dest PATH.")
+        selected = prompt("Escopo: [p]rojeto atual ou [g]lobal? [p]").lower()
+        if selected not in ("", "p", "g"):
+            raise CrowError("usage", "Escopo inválido.")
+        if selected != "g":
+            project = str(Path.cwd())
+    if project:
+        project = checked(project)
+        if not project.is_dir():
+            raise CrowError("usage", "O diretório do projeto deve existir.")
+    if not agents and not custom:
+        if read:
+            agents = ",".join(AGENTS)
+        elif interactive:
+            agents = prompt("Agentes separados por vírgula (" + ",".join(AGENTS) + "):")
+    return destinations(agents, home, project, custom)
+
+
+def authorize(args, interactive, summary):
+    if getattr(args, "dry_run", False) or getattr(args, "yes", False):
+        return
+    if not interactive:
+        raise CrowError("confirmation_required", "Use --dry-run para preview ou --yes para aplicar o escopo explícito.")
+    print(json.dumps(summary, ensure_ascii=False, indent=2), file=sys.stderr)
+    if prompt("Aplicar estas alterações? [s/N]").lower() not in ("s", "sim", "y", "yes"):
+        raise CrowError("cancelled", "Operação cancelada; nenhuma instalação alterada.")
+
+
+def relationship_view(source, name, store, targets):
+    relations = source.related(name)
+    names = set(relations["handoffs"] + relations["used_by"] + relations["behaviour_overlays"] + relations["can_coordinate"])
+    return {**relations, "availability": [r for r in store.status(targets, names) if r["name"] in names] if names else [],
+            "meaning": "Handoffs e overlays são complementos opcionais, não dependências nem ordem automática de execução."}
+
+
+def run(args):
+    if args.version:
+        return {"version": __version__}
+    if not args.command:
+        raise CrowError("usage", "Escolha um comando; use crow-skills --help.")
+    home = checked(getattr(args, "home", Path.home()))
+    store = Store(home)
+    interactive = sys.stdin.isatty() and not getattr(args, "non_interactive", False) and not getattr(args, "json", False)
+    if getattr(args, "fetch", False) and (getattr(args, "dry_run", False) or args.command not in ("install", "update", "list", "info", "related")):
+        raise CrowError("usage", "--fetch requer um comando com fonte e não pode ser combinado com --dry-run.")
+    if args.command == "agents":
+        return {"agents": inventory(home), "note": "Detecção por PATH/diretórios não comprova carregamento da skill."}
+    if args.command in ("status", "doctor"):
+        targets = scope(args, home, read=True)
+        rows = store.status(targets)
+        pending = [t["id"] for t in store.pending()]
+        result = {"installations": rows, "pending_transactions": pending,
+                  "activation_verified": False, "reload_hint": "Peça ao host para recarregar/listar skills; reinicie a sessão se necessário."}
+        if args.command == "doctor":
+            result.update(healthy=not pending and all(r["status"] not in ("modified", "missing", "unsafe") for r in rows), agents=inventory(home))
+        return result
+    if args.command in ("rollback", "recover"):
+        if any(getattr(args, k, None) for k in ("agents", "dest", "project", "global_scope")):
+            raise CrowError("usage", "Rollback/recover usam os destinos registrados na transação, sem filtros de agente/escopo.")
+        ids = [args.transaction] if args.transaction else [t["id"] for t in store.pending()]
+        transactions = [store.journal(txid) for txid in ids]
+        expected = ("prepared", "restoring") if args.command == "recover" else ("committed",)
+        if any(t["phase"] not in expected for t in transactions):
+            raise CrowError("invalid_transaction", "Transação incompatível com a operação.")
+        summary = {"transactions": [{"id": t["id"], "targets": list(t["before"])} for t in transactions]}
+        if transactions:
+            authorize(args, interactive, summary)
+        if not getattr(args, "dry_run", False):
+            for txid in ids:
+                store.rollback(txid, recovery=args.command == "recover")
+        return {**summary, "dry_run": getattr(args, "dry_run", False), "applied": not getattr(args, "dry_run", False)}
+    source = None
+    if args.command != "uninstall":
+        source = Source(getattr(args, "source", DEFAULT_SOURCE), getattr(args, "ref", "HEAD"), getattr(args, "fetch", False))
+    if args.command == "list":
+        return {"revision": source.revision, "source": str(source.path), "skills": list(source.catalog.values()),
+                "composition": {"overlays": source.overlays}, "handoffs_are_optional": True}
+    if args.command in ("info", "related"):
+        source.require(args.name)
+        targets = scope(args, home, read=True)
+        return {"revision": source.revision, "skill": source.catalog[args.name],
+                "relationships": relationship_view(source, args.name, store, targets)}
+    targets = scope(args, home, interactive)
+    names = args.skills
+    if names and args.all:
+        raise CrowError("usage", "Use nomes ou --all, não ambos.")
+    if args.command == "install" and not names and not args.all:
+        if not interactive:
+            raise CrowError("usage", "Escolha nomes de skills ou --all.")
+        for name, item in source.catalog.items():
+            print(terminal(name + " — " + item.get("title", name)), file=sys.stderr)
+        names = prompt("Skills separadas por vírgula:").split(",")
+        names = [n.strip() for n in names if n.strip()]
+        if not names:
+            raise CrowError("usage", "Nenhuma skill selecionada.")
+    if args.command == "uninstall" and not names and not args.all:
+        raise CrowError("usage", "Uninstall exige nomes explícitos ou --all.")
+    if args.command == "install" and args.all:
+        names = list(source.catalog)
+    names = list(dict.fromkeys(names))
+    if getattr(args, "with_handoffs", False):
+        if not names:
+            raise CrowError("usage", "--with-handoffs exige nomes explícitos.")
+        for name in list(names):
+            source.require(name)
+            names.extend(n for n in source.catalog[name]["next"] if n not in names)
+    plan = store.plan(args.command, names, targets, source, getattr(args, "replace", False), args.overwrite_modified)
+    summary = {"changes": plan["changes"], "revision": source.revision if source else None,
+               "relationships": {n: source.related(n) for n in names} if source else {},
+               "handoffs_are_optional": True, "activation_verified": False}
+    if plan["items"]:
+        authorize(args, interactive, summary)
+    txid = None if getattr(args, "dry_run", False) else store.apply(plan)
+    return {**summary, "transaction": txid, "dry_run": getattr(args, "dry_run", False),
+            "applied": not getattr(args, "dry_run", False),
+            "reload_hint": ("Somente preview; nada instalado." if getattr(args, "dry_run", False) else
+                            "Operação de arquivos concluída; carregamento/ativação devem ser conferidos no host.")}
+
+
+def emit(command, data, machine):
+    envelope = {"schema_version": 1, "ok": True, "command": command, "data": data}
+    if machine:
+        print(json.dumps(envelope, ensure_ascii=False, separators=(",", ":")))
+    elif command == "list":
+        print("Fonte: " + data["revision"])
+        for item in data["skills"]:
+            print(terminal(f"{item['name']} [{item['role']}] → {item['owns']}\n  {item['description']}"))
+    else:
+        print(terminal(json.dumps(data, ensure_ascii=False, indent=2)))
+
+
+def main(argv=None):
+    argv = list(sys.argv[1:] if argv is None else argv)
+    machine = "--json" in argv
+    command = None
+    try:
+        args = parser().parse_args(argv)
+        command = args.command or ("version" if args.version else None)
+        result = run(args)
+        emit(command, result, machine)
+        return 0
+    except CrowError as exc:
+        if machine:
+            print(json.dumps({"schema_version": 1, "ok": False, "command": command,
+                              "error": {"code": exc.code, "message": str(exc)}}, ensure_ascii=False))
+        else:
+            print(f"Erro [{exc.code}]: {exc}", file=sys.stderr)
+        return 2 if exc.code == "usage" else 1
+    except (OSError, ValueError, KeyError, TypeError) as exc:
+        # No traceback or subprocess stderr in machine output; credentials stay external.
+        if machine:
+            print(json.dumps({"schema_version": 1, "ok": False, "command": command,
+                              "error": {"code": "io_error", "message": "Falha de leitura/gravação ou estado inválido; nenhuma conclusão de sucesso."}}))
+        else:
+            print("Falha de leitura/gravação ou estado inválido. Confira permissões, origem e transações pendentes.", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        if machine:
+            print(json.dumps({"schema_version": 1, "ok": False, "command": command,
+                              "error": {"code": "interrupted", "message": "Operação interrompida; confira status/recover."}}))
+        return 130

package/crow_skills/npm_entry.py

@@ -0,0 +1,14 @@
+"""Isolated Python entry used by the npm launcher, not imported as package code."""
+from pathlib import Path
+import json
+import sys
+
+if sys.version_info < (3, 10):
+    error = {"schema_version": 1, "ok": False, "command": None,
+             "error": {"code": "python_version", "message": "Python 3.10+ é necessário."}}
+    print(json.dumps(error) if "--json" in sys.argv else error["error"]["message"])
+    raise SystemExit(1)
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from crow_skills.cli import main
+
+raise SystemExit(main())

package/crow_skills/source.py

@@ -0,0 +1,256 @@
+"""Read committed Git objects as data. Never check out or execute package code."""
+from dataclasses import dataclass
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+import re
+import stat
+import subprocess
+
+NAME = re.compile(r"crow-[a-z0-9]+(?:-[a-z0-9]+)*\Z")
+SHA = re.compile(r"[a-f0-9]{40,64}\Z")
+MAX_FILE = 8 * 1024 * 1024
+MAX_PACKAGE = 32 * 1024 * 1024
+MAX_FILES = 2000
+
+
+class CrowError(Exception):
+    def __init__(self, code, message):
+        super().__init__(message)
+        self.code = code
+
+
+def valid_name(name):
+    if not isinstance(name, str) or not NAME.fullmatch(name) or len(name) >= 64:
+        raise CrowError("invalid_name", "Nome de skill inválido; use crow-nome.")
+    return name
+
+
+def safe_relative(value):
+    p = PurePosixPath(value)
+    if (not value or p.is_absolute() or str(p) != value or
+            any(x in (".", "..") for x in p.parts) or "\\" in value or
+            any(ord(c) < 32 or ord(c) == 127 for c in value)):
+        raise CrowError("unsafe_path", "Caminho de recurso inválido no pacote.")
+    return p
+
+
+def file_entry(data, executable=False):
+    return {"kind": "file", "sha256": hashlib.sha256(data).hexdigest(),
+            "executable": bool(executable)}
+
+
+def entries_for(files):
+    entries = {}
+    for name, (data, executable) in files.items():
+        entries[name] = file_entry(data, executable)
+        for parent in PurePosixPath(name).parents:
+            if str(parent) != ".":
+                entries[str(parent)] = {"kind": "dir"}
+    return dict(sorted(entries.items()))
+
+
+def digest(entries):
+    return hashlib.sha256(json.dumps(entries, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+
+
+@dataclass
+class Package:
+    name: str
+    files: dict
+    entries: dict
+
+    def materialize(self, target):
+        target.mkdir(mode=0o700)
+        for name, (data, executable) in self.files.items():
+            p = target / name
+            p.parent.mkdir(parents=True, exist_ok=True)
+            p.write_bytes(data)
+            p.chmod(0o755 if executable else 0o644)
+
+
+class Source:
+    def __init__(self, path, ref="HEAD", fetch=False):
+        self.path = Path(path).expanduser().resolve(strict=True)
+        self.bundle = None
+        if (self.path / "release.json").exists() and not (self.path / ".git").exists():
+            if fetch:
+                raise CrowError("immutable_release", "Pacote npm é um snapshot; atualize o pacote npm ou selecione --source com clone Git.")
+            self._init_bundle()
+            if ref not in ("HEAD", self.revision):
+                raise CrowError("immutable_release", "A referência não está neste snapshot npm; selecione um clone Git para outras refs.")
+            raw = self.bundle_file("catalog.json")
+        else:
+            if fetch:
+                self.git("fetch", "--no-recurse-submodules", "origin", timeout=120)
+            self.revision = self.git("rev-parse", "--verify", "--end-of-options", ref + "^{commit}").decode().strip()
+            raw = self.git("show", self.revision + ":catalog.json")
+        if not SHA.fullmatch(self.revision):
+            raise CrowError("invalid_revision", "A referência não resolveu para um commit.")
+        try:
+            if len(raw) > 1024 * 1024:
+                raise ValueError("catalog too large")
+            data = json.loads(raw)
+            skills = data["skills"]
+            if data["version"] != 1 or not isinstance(skills, list) or len(skills) > 1000:
+                raise ValueError("invalid schema")
+            self.catalog = {}
+            owners = set()
+            for item in skills:
+                name = valid_name(item["name"])
+                if (name in self.catalog or not isinstance(item["description"], str) or
+                        not isinstance(item["owns"], str) or not item["owns"] or item["owns"] in owners or
+                        item["role"] not in ("coordinator", "specialist", "reviewer") or
+                        not isinstance(item["next"], list)):
+                    raise ValueError("invalid entry")
+                owners.add(item["owns"])
+                self.catalog[name] = item
+            for item in skills:
+                if len(item["next"]) != len(set(item["next"])) or any(n not in self.catalog or n == item["name"] for n in item["next"]):
+                    raise ValueError("invalid handoff")
+            composition = data.get("composition", {})
+            if not isinstance(composition, dict):
+                raise ValueError("invalid composition")
+            self.overlays = composition.get("overlays", [])
+            if not isinstance(self.overlays, list):
+                raise ValueError("invalid overlays")
+            for overlay in self.overlays:
+                if overlay["skill"] not in self.catalog or not isinstance(overlay["roles"], list) or any(r not in ("coordinator", "specialist", "reviewer") for r in overlay["roles"]):
+                    raise ValueError("invalid overlay")
+        except (ValueError, KeyError, TypeError) as exc:
+            raise CrowError("invalid_catalog", "Catálogo inválido no commit selecionado.") from exc
+
+    def _init_bundle(self):
+        try:
+            p = self.path / "release.json"
+            if p.is_symlink() or p.stat().st_size > 2 * 1024 * 1024:
+                raise ValueError("manifest")
+            data = json.loads(p.read_bytes())
+            if data["schema_version"] != 1 or not SHA.fullmatch(data["revision"]) or not isinstance(data["files"], dict) or len(data["files"]) > 40000:
+                raise ValueError("schema")
+            for name, entry in data["files"].items():
+                safe_relative(name)
+                if (not isinstance(entry, dict) or set(entry) != {"kind", "sha256", "executable"} or entry["kind"] != "file" or
+                        not isinstance(entry["sha256"], str) or not re.fullmatch(r"[a-f0-9]{64}", entry["sha256"]) or not isinstance(entry["executable"], bool)):
+                    raise ValueError("entry")
+            self.bundle = data["files"]
+            self.revision = data["revision"]
+        except (OSError, ValueError, TypeError, KeyError) as exc:
+            raise CrowError("invalid_release", "Manifesto do snapshot npm inválido.") from exc
+
+    def bundle_file(self, name):
+        safe_relative(name)
+        try:
+            p = self.path / name
+            for item in (p, *p.parents):
+                if item == self.path:
+                    break
+                if item.is_symlink():
+                    raise ValueError("symlink")
+            info = p.stat()
+            if not stat.S_ISREG(info.st_mode) or info.st_size > MAX_FILE:
+                raise ValueError("size/type")
+            data = p.read_bytes()
+            if file_entry(data, bool(info.st_mode & 0o111)) != self.bundle[name]:
+                raise ValueError("digest/mode")
+            return data
+        except (OSError, KeyError, ValueError) as exc:
+            raise CrowError("invalid_release", "Recurso ausente, alterado ou inseguro no snapshot npm.") from exc
+
+    def git(self, *args, timeout=30):
+        try:
+            result = subprocess.run(["git", "--no-replace-objects", "-c", "core.hooksPath=/dev/null", "-c", "gc.auto=0",
+                                     "-c", "protocol.ext.allow=never", "-C", str(self.path), *args],
+                                    stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=timeout)
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise CrowError("git_unavailable", "Git indisponível ou operação excedeu o tempo limite.") from exc
+        if result.returncode:
+            # Git/auth helpers can print credentials: never echo their stderr.
+            raise CrowError("git_failed", "Git falhou. Verifique clone, referência e acesso ao origin; stderr omitido para proteger credenciais.")
+        return result.stdout
+
+    def related(self, name):
+        self.require(name)
+        return {
+            "handoffs": list(self.catalog[name]["next"]),
+            "used_by": [n for n, v in self.catalog.items() if name in v["next"]],
+            "behaviour_overlays": [v["skill"] for v in self.overlays
+                                   if v["skill"] != name and self.catalog[name]["role"] in v["roles"]],
+            "can_coordinate": [n for v in self.overlays if v["skill"] == name
+                               for n, item in self.catalog.items() if n != name and item["role"] in v["roles"]],
+            "optional": True,
+        }
+
+    def require(self, name):
+        valid_name(name)
+        if name not in self.catalog:
+            raise CrowError("unknown_skill", "Skill não encontrada no catálogo selecionado: " + name)
+
+    def _git_files(self, name):
+        prefix = "skills/" + name + "/"
+        raw = self.git("ls-tree", "-r", "-z", "-l", self.revision, "--", prefix)
+        files = {}
+        total = 0
+        for record in raw.split(b"\0"):
+            if not record:
+                continue
+            try:
+                header, path = record.split(b"\t", 1)
+                mode, kind, oid, size = header.split()
+                path = path.decode("utf-8")
+                if not path.startswith(prefix):
+                    raise ValueError("prefix")
+                rel = path[len(prefix):]
+                safe_relative(rel)
+                if mode not in (b"100644", b"100755") or kind != b"blob":
+                    raise CrowError("unsafe_source", "Symlinks, submódulos e arquivos especiais não são instaláveis.")
+                size = int(size)
+                total += size
+                if size > MAX_FILE or total > MAX_PACKAGE or len(files) >= MAX_FILES:
+                    raise CrowError("package_limit", "Pacote excede limite de tamanho/arquivos.")
+                blob = self.git("cat-file", "blob", oid.decode())
+                if len(blob) != size:
+                    raise ValueError("size")
+                files[rel] = (blob, mode == b"100755")
+            except (ValueError, UnicodeError) as exc:
+                raise CrowError("unsafe_source", "Inventário de pacote inválido.") from exc
+        return files
+
+    def package(self, name):
+        self.require(name)
+        if self.bundle is None:
+            files = self._git_files(name)
+        else:
+            prefix = "skills/" + name + "/"
+            files = {}
+            total = 0
+            for path, entry in self.bundle.items():
+                if not path.startswith(prefix):
+                    continue
+                data = self.bundle_file(path)
+                total += len(data)
+                if total > MAX_PACKAGE or len(files) >= MAX_FILES:
+                    raise CrowError("package_limit", "Snapshot excede limite de tamanho/arquivos.")
+                files[path[len(prefix):]] = (data, entry["executable"])
+        if "SKILL.md" not in files:
+            raise CrowError("invalid_package", "SKILL.md ausente do pacote.")
+        try:
+            text = files["SKILL.md"][0].decode("utf-8")
+            head, sep, _ = text[4:].partition("\n---\n")
+            values = dict(line.split(":", 1) for line in head.splitlines())
+            if not text.startswith("---\n") or not sep or values["name"].strip() != name or json.loads(values["description"].strip()) != self.catalog[name]["description"]:
+                raise ValueError("frontmatter mismatch")
+            # Parse only the repository's documented simple YAML subset, never execute it.
+            for rel, (content, _) in files.items():
+                if rel.endswith(".md"):
+                    for link in re.findall(r"!?\[[^\]]*\]\(([^)\s]+)\)", content.decode("utf-8")):
+                        if "://" in link or link.startswith(("#", "mailto:")):
+                            continue
+                        import posixpath
+                        joined = posixpath.normpath(posixpath.join(posixpath.dirname(rel), link.split("#", 1)[0]))
+                        safe_relative(joined)
+                        if joined not in files:
+                            raise ValueError("missing reference")
+        except (ValueError, KeyError, UnicodeError) as exc:
+            raise CrowError("invalid_package", "Frontmatter/referências do pacote não correspondem ao catálogo.") from exc
+        return Package(name, files, entries_for(files))