Skip to content

bird-chinese-community/BIRD.skills / bird-agent

bird-agent

Verified

Write, review, discover, lint, format, and validate BIRD 2/3 routing-daemon projects with the @birdcc toolchain. Use for bird.conf, bird2.conf, bird3.conf, bird6.conf, .bird/.bird2/.bird3 files, bird.config.json, birdcc.config.json, include graphs, BIRD filters and protocols, birdcc init/lint/fmt/lsp, or bird -p checks. Treat BIRD 1 as legacy and verify it with the actual BIRD 1 binary. Route editor and CLI installation to birdcc-installer, GitHub Actions to birdcc-cicd, runtime incidents to bird-troubleshooting, and implementation archaeology to bird-source-explorer.

scripts/detect_bird_context.py

View on GitHub
# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

"""Detect BIRD configuration context in the current working directory."""

from __future__ import annotations

import argparse
import json
import re
import shutil
import subprocess
import sys
from pathlib import Path

VERSION_RE = re.compile(r"^bird(\d+|6)?\.conf$")
CONFIG_FILE_NAMES = ("bird.config.json", "birdcc.config.json")
CONFIG_SUFFIXES = (".conf", ".bird", ".bird2", ".bird3")

# Do not read files larger than this when sampling for BIRD keywords.
MAX_SAMPLE_BYTES = 10 * 1024 * 1024

# Number of bytes to sample from the start of a candidate config file.
SAMPLE_BYTES = 2048


def version_from_filename(path: Path) -> str | None:
    """Infer BIRD version from a config filename."""
    if path.suffix in {".bird2", ".bird3"}:
        return path.suffix.removeprefix(".bird")
    match = VERSION_RE.search(path.name)
    if not match:
        return None
    hint = match.group(1)
    if hint == "6":
        return "2"  # bird6.conf is typically BIRD2 IPv6
    return hint


def _is_within_root(path: Path, root: Path) -> bool:
    """Return True if path is the same as or inside root after resolving symlinks."""
    try:
        path.resolve().relative_to(root.resolve())
    except (ValueError, OSError):
        return False
    return True


def find_bird_configs(root: Path, max_depth: int = 3) -> list[dict[str, object]]:
    """Find BIRD config files under root up to max_depth."""
    configs: list[dict[str, object]] = []
    seen: set[Path] = set()

    for depth in range(max_depth + 1):
        pattern = "*/" * depth + "*"
        for path in sorted(root.glob(pattern)):
            if path in seen:
                continue
            seen.add(path)
            if not path.name.endswith(CONFIG_SUFFIXES):
                continue
            if not path.is_file():
                continue
            if path.name in {"nginx.conf", "haproxy.conf", "my.cnf"}:
                continue
            # Guard against symlink escapes and unusual filesystem entries.
            if not _is_within_root(path, root):
                continue
            try:
                st = path.stat(follow_symlinks=True)
            except OSError:
                continue
            if st.st_size > MAX_SAMPLE_BYTES:
                continue
            # Heuristic: require at least one BIRD keyword in the first 2 KB.
            try:
                with path.open("rb") as f:
                    sample = f.read(SAMPLE_BYTES).decode("utf-8", errors="ignore")
            except OSError:
                continue
            if not re.search(
                r"\b(protocol|filter|function|router\s+id|local\s+as|neighbor|define|table)\b",
                sample,
                re.IGNORECASE,
            ):
                continue
            configs.append(
                {
                    "path": str(path.relative_to(root)),
                    "version_hint": version_from_filename(path),
                }
            )

    return configs


def find_bird_project_config(root: Path) -> dict[str, object] | None:
    """Find the preferred project config or its backwards-compatible alias."""
    for name in CONFIG_FILE_NAMES:
        candidate = root / name
        if candidate.is_file() and _is_within_root(candidate, root):
            return {
                "path": str(candidate.relative_to(root)),
                "preferred": name == "bird.config.json",
                "compatibility_alias": name == "birdcc.config.json",
            }
    return None


def birdcc_package_version(executable: str) -> str | None:
    """Read the package version near a resolved birdcc Node.js entry point."""
    try:
        resolved = Path(executable).resolve(strict=True)
    except OSError:
        return None

    for parent in (resolved.parent, *list(resolved.parents)[:6]):
        package_json = parent / "package.json"
        if not package_json.is_file():
            continue
        try:
            package = json.loads(package_json.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError):
            continue
        if package.get("name") == "@birdcc/cli" and isinstance(
            package.get("version"), str
        ):
            return package["version"]
    return None


def birdcc_info() -> dict[str, object]:
    """Check whether birdcc is available and get its version."""
    executable = shutil.which("birdcc")
    if not executable:
        return {"available": False, "version": None, "path": None}
    version = birdcc_package_version(executable)
    try:
        result = subprocess.run(
            [executable, "--help"],
            capture_output=True,
            text=True,
            check=False,
            timeout=10,
        )
        command_available = result.returncode == 0
    except (OSError, subprocess.TimeoutExpired):
        command_available = False
    return {
        "available": command_available,
        "version": version,
        "version_source": "package.json" if version else None,
        "path": executable,
    }


def birdcc_project_detection(
    root: Path, executable: str | None, max_depth: int
) -> dict[str, object] | None:
    """Run the CLI's authoritative entry-point detector without writing files."""
    if not executable:
        return None

    try:
        result = subprocess.run(
            [
                executable,
                "init",
                str(root),
                "--dry-run",
                "--json",
                "--max-depth",
                str(max_depth),
            ],
            capture_output=True,
            text=True,
            check=False,
            timeout=30,
        )
    except (OSError, subprocess.TimeoutExpired):
        return None

    output = result.stdout.strip()
    try:
        report = json.loads(output) if output else None
    except json.JSONDecodeError:
        report = None

    return {
        "command_supported": report is not None,
        "returncode": result.returncode,
        "report": report,
        "stderr": result.stderr.strip() or None,
    }


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Detect BIRD configuration files and toolchain availability."
    )
    parser.add_argument(
        "--root",
        type=Path,
        default=Path.cwd(),
        help="Project root to scan (default: current directory).",
    )
    parser.add_argument(
        "--max-depth",
        type=int,
        default=3,
        help="Maximum directory depth to scan for config files (default: 3).",
    )
    args = parser.parse_args(argv)

    try:
        root = args.root.resolve()
    except OSError as exc:
        parser.error(f"cannot resolve --root: {args.root}: {exc}")

    if not root.is_dir():
        parser.error(f"--root must be a directory: {root}")
    if args.max_depth < 0:
        parser.error("--max-depth must be non-negative")

    cli = birdcc_info()
    result = {
        "root": str(root),
        "project_config": find_bird_project_config(root),
        "config_files": find_bird_configs(root, max_depth=args.max_depth),
        "birdcc": cli,
        "birdcc_project_detection": birdcc_project_detection(
            root,
            cli["path"] if isinstance(cli["path"], str) else None,
            args.max_depth,
        ),
    }

    json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
    sys.stdout.write("\n")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall