feat(tools): install every discovered portal CLI with one command (#540) (#541)

README and SETUP.md hardcoded the six shipped portals in four PowerShell/Bash
loops, so a portal added by /add-portal or borrowed from another fork was
skipped on a fresh clone. tools/install_portal_clis.py uses CI's discover-clis
glob, isolates per-CLI failures, and skips manifests with lifecycle scripts or
trustedDependencies.

tools/install_portal_clis.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Install the dependencies of every portal CLI under .agents/skills/.
+
+Run from anywhere: python3 tools/install_portal_clis.py [--dry-run]
+
+The CLIs are discovered, not listed: every `.agents/skills/*/cli/package.json`
+is installed, the same glob CI's discover-clis job uses. A portal generated by
+/add-portal or copied from another fork is therefore picked up on a fresh clone
+without anyone editing an install loop, and a portal removed from the tree
+stops being asked for.
+
+One command for every shell, since Python is already a prerequisite - the
+README previously carried a PowerShell and a Bash loop, each with its own
+hand-copied list of portal names.
+
+A manifest that declares an npm/bun lifecycle script or trustedDependencies is
+skipped and reported instead of installed: those are the hooks that run code
+during `bun install`, and tools/security_guards.py forbids them in-tree. A
+borrowed portal that carries one gets read by a human before it runs.
+
+Each CLI installs independently; one failure does not stop the rest. Exit 0
+when every CLI installed, 1 when bun is missing, a manifest was skipped, or an
+install failed.
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from security_guards import FORBIDDEN_SCRIPTS  # noqa: E402
+
+
+def discover(root: Path = ROOT) -> list[Path]:
+    """Return each portal CLI directory, sorted by portal name."""
+    return sorted(p.parent for p in (root / ".agents" / "skills").glob("*/cli/package.json"))
+
+
+def unsafe_reason(cli_dir: Path) -> str | None:
+    """Why this manifest must not be installed unattended, or None when it is safe."""
+    try:
+        data = json.loads((cli_dir / "package.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return f"unreadable package.json ({exc})"
+    if not isinstance(data, dict):
+        return "package.json is not a JSON object"
+    scripts = data.get("scripts", {})
+    bad = sorted(FORBIDDEN_SCRIPTS & set(scripts)) if isinstance(scripts, dict) else []
+    if bad:
+        return f"declares lifecycle script(s) {bad}"
+    if "trustedDependencies" in data:
+        return "declares trustedDependencies"
+    return None
+
+
+def install(cli_dirs: list[Path], bun: str, dry_run: bool, root: Path = ROOT, run=subprocess.run) -> int:
+    failures = []
+    for cli_dir in cli_dirs:
+        name = cli_dir.parent.name
+        reason = unsafe_reason(cli_dir)
+        if reason:
+            print(f"SKIP  {name}: {reason} - read its code, then run `bun install` in "
+                  f"{cli_dir.relative_to(root).as_posix()} yourself if you trust it")
+            failures.append(name)
+            continue
+        if dry_run:
+            print(f"would install  {name}")
+            continue
+        print(f"installing  {name}", flush=True)
+        if run([bun, "install"], cwd=cli_dir).returncode != 0:
+            print(f"FAIL  {name}: bun install exited non-zero")
+            failures.append(name)
+    if failures:
+        print(f"\n{len(failures)} of {len(cli_dirs)} portal CLI(s) not installed: {', '.join(failures)}")
+        return 1
+    verb = "would be installed" if dry_run else "installed"
+    print(f"\nAll {len(cli_dirs)} portal CLI(s) {verb}.")
+    return 0
+
+
+def _force_utf8_output() -> None:
+    """Write UTF-8 whatever the host's default encoding is (a fork's portal name may not be ASCII)."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)  # absent on a StringIO under test
+        if reconfigure:
+            reconfigure(encoding="utf-8")
+
+
+def main() -> int:
+    _force_utf8_output()
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--dry-run", action="store_true", help="list what would be installed, run nothing")
+    args = ap.parse_args()
+
+    cli_dirs = discover()
+    if not cli_dirs:
+        print("No portal CLIs found under .agents/skills/*/cli/ - nothing to install.")
+        return 0
+    bun = shutil.which("bun")
+    if not bun and not args.dry_run:
+        print("bun is not on PATH. Install it from https://bun.sh, open a new shell, and re-run.")
+        return 1
+    return install(cli_dirs, bun or "bun", args.dry_run)
+
+
+if __name__ == "__main__":
+    sys.exit(main())