tribunal-kit 1.0.0

package/.agent/scripts/auto_preview.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""
+auto_preview.py — Start, stop, or check a local development server.
+
+Usage:
+  python .agent/scripts/auto_preview.py start
+  python .agent/scripts/auto_preview.py stop
+  python .agent/scripts/auto_preview.py status
+  python .agent/scripts/auto_preview.py restart
+"""
+
+import os
+import sys
+import json
+import time
+import signal
+import socket
+import subprocess
+from pathlib import Path
+
+PID_FILE = ".preview.pid"
+DEFAULT_PORT = 3000
+TIMEOUT_SECONDS = 30
+
+GREEN  = "\033[92m"
+RED    = "\033[91m"
+YELLOW = "\033[93m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+
+def find_start_command() -> tuple[list[str], bool]:
+    """
+    Read package.json for a dev/start script.
+    Returns (command, found) — found=False if no package.json or no scripts.
+    """
+    pkg_path = Path("package.json")
+    if not pkg_path.exists():
+        return [], False
+
+    try:
+        with open(pkg_path) as f:
+            pkg = json.load(f)
+        scripts = pkg.get("scripts", {})
+        if "dev" in scripts:
+            return ["npm", "run", "dev"], True
+        elif "start" in scripts:
+            return ["npm", "run", "start"], True
+        else:
+            return [], False
+    except (json.JSONDecodeError, IOError):
+        return [], False
+
+
+def get_port_from_env() -> int:
+    env_path = Path(".env")
+    if env_path.exists():
+        try:
+            with open(env_path) as f:
+                for line in f:
+                    if line.startswith("PORT="):
+                        return int(line.split("=")[1].strip())
+        except (ValueError, IOError):
+            pass
+    return DEFAULT_PORT
+
+
+def is_port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(1)
+        return s.connect_ex(("localhost", port)) == 0
+
+
+def read_pid() -> int | None:
+    pid_file = Path(PID_FILE)
+    if pid_file.exists():
+        try:
+            return int(pid_file.read_text().strip())
+        except (ValueError, IOError):
+            pass
+    return None
+
+
+def write_pid(pid: int) -> None:
+    Path(PID_FILE).write_text(str(pid))
+
+
+def clear_pid() -> None:
+    pid_file = Path(PID_FILE)
+    if pid_file.exists():
+        pid_file.unlink()
+
+
+def start_server() -> None:
+    port = get_port_from_env()
+
+    if is_port_open(port):
+        print(f"{YELLOW}⚠️  Port {port} is already in use.{RESET}")
+        pid = read_pid()
+        if pid:
+            print(f"   Known PID: {pid}")
+        return
+
+    cmd, found = find_start_command()
+    if not found:
+        print(f"{RED}❌ No dev/start script found.{RESET}")
+        print(f"   This project has no package.json, or its package.json has no 'dev' or 'start' script.")
+        print(f"   Add a script to package.json, or start your server manually.")
+        return
+
+    print(f"{BOLD}Starting: {' '.join(cmd)}{RESET}")
+    proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True)
+    write_pid(proc.pid)
+
+    print(f"Waiting for port {port}…", end="", flush=True)
+    for _ in range(TIMEOUT_SECONDS):
+        if is_port_open(port):
+            print()
+            print(f"\n{GREEN}✅ Server started{RESET}")
+            print(f"   URL:     http://localhost:{port}")
+            print(f"   PID:     {proc.pid}")
+            print(f"   Command: {' '.join(cmd)}")
+            print(f"\nStop with: python .agent/scripts/auto_preview.py stop")
+            return
+        print(".", end="", flush=True)
+        time.sleep(1)
+
+    print()
+    print(f"{RED}❌ Server did not start within {TIMEOUT_SECONDS}s{RESET}")
+    proc.terminate()
+    clear_pid()
+
+
+def stop_server() -> None:
+    pid = read_pid()
+    if not pid:
+        print(f"{YELLOW}⚠️  No stored server PID found{RESET}")
+        return
+    try:
+        os.kill(pid, signal.SIGTERM)
+        time.sleep(1)
+        print(f"{GREEN}✅ Server stopped (PID {pid}){RESET}")
+    except ProcessLookupError:
+        print(f"{YELLOW}Process {pid} was not running{RESET}")
+    finally:
+        clear_pid()
+
+
+def show_status() -> None:
+    port = get_port_from_env()
+    pid = read_pid()
+    if is_port_open(port):
+        print(f"{GREEN}🟢 Running — http://localhost:{port}{RESET}")
+        if pid:
+            print(f"   PID: {pid}")
+    else:
+        print(f"{RED}🔴 Not running on port {port}{RESET}")
+
+
+def main() -> None:
+    actions = {"start", "stop", "status", "restart"}
+    if len(sys.argv) < 2 or sys.argv[1] not in actions:
+        print(f"Usage: auto_preview.py [start|stop|status|restart]")
+        sys.exit(1)
+
+    action = sys.argv[1]
+    if action == "start":
+        start_server()
+    elif action == "stop":
+        stop_server()
+    elif action == "status":
+        show_status()
+    elif action == "restart":
+        stop_server()
+        time.sleep(1)
+        start_server()
+
+
+if __name__ == "__main__":
+    main()

package/.agent/scripts/checklist.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+checklist.py — Priority-based project audit runner for the Tribunal Agent Kit.
+
+Runs a tiered audit sequence:
+  Priority 1: Security
+  Priority 2: Lint
+  Priority 3: Schema validation
+  Priority 4: Tests
+  Priority 5: UX / Accessibility
+  Priority 6: SEO
+  Priority 7: Lighthouse / E2E (requires --url)
+
+Usage:
+  python .agent/scripts/checklist.py .
+  python .agent/scripts/checklist.py . --url http://localhost:3000
+  python .agent/scripts/checklist.py . --skip security,seo
+"""
+
+import os
+import sys
+import subprocess
+import argparse
+from pathlib import Path
+
+# ━━━ ANSI color output ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+BLUE = "\033[94m"
+RESET = "\033[0m"
+BOLD = "\033[1m"
+
+
+def print_header(title: str) -> None:
+    print(f"\n{BOLD}{BLUE}━━━ {title} ━━━{RESET}")
+
+
+def print_ok(msg: str) -> None:
+    print(f"  {GREEN}✅ {msg}{RESET}")
+
+
+def print_fail(msg: str) -> None:
+    print(f"  {RED}❌ {msg}{RESET}")
+
+
+def print_skip(msg: str) -> None:
+    print(f"  {YELLOW}⏭️  Skipped: {msg}{RESET}")
+
+
+def run_check(label: str, cmd: list[str], cwd: str) -> bool:
+    """Run a shell command and return True if it exits with code 0."""
+    try:
+        result = subprocess.run(
+            cmd,
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0:
+            print_ok(f"{label} passed")
+            return True
+        else:
+            print_fail(f"{label} failed")
+            if result.stdout.strip():
+                print(f"    {result.stdout.strip()[:500]}")
+            if result.stderr.strip():
+                print(f"    {result.stderr.strip()[:500]}")
+            return False
+    except FileNotFoundError:
+        print_skip(f"{label} — command not found (tool not installed)")
+        return True  # Don't block on tools that aren't installed
+    except subprocess.TimeoutExpired:
+        print_fail(f"{label} — timed out after 60s")
+        return False
+
+
+def check_secrets(project_root: str) -> bool:
+    """Scan for hardcoded secrets in source files."""
+    print_header("Security — Secret Scan")
+    dangerous_patterns = [
+        "password=",
+        "secret=",
+        "api_key=",
+        "apikey=",
+        "AUTH_TOKEN=",
+        "PRIVATE_KEY=",
+    ]
+    found_issues = False
+    source_extensions = {".ts", ".tsx", ".js", ".jsx", ".py", ".env"}
+
+    for root, dirs, files in os.walk(project_root):
+        # Skip known-safe directories
+        dirs[:] = [d for d in dirs if d not in {"node_modules", ".git", ".agent", "dist", "__pycache__"}]
+        for filename in files:
+            if not any(filename.endswith(ext) for ext in source_extensions):
+                continue
+            if filename.startswith(".env"):
+                continue  # .env files are allowed to have these
+            filepath = os.path.join(root, filename)
+            try:
+                with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                    for line_num, line in enumerate(f, 1):
+                        line_lower = line.lower().strip()
+                        if any(pattern in line_lower for pattern in dangerous_patterns):
+                            # Only flag if it looks like an actual value (contains = and a non-empty value)
+                            if "=" in line and not line_lower.strip().startswith("#"):
+                                rel = os.path.relpath(filepath, project_root)
+                                print_fail(f"Possible secret: {rel}:{line_num} → {line.strip()[:80]}")
+                                found_issues = True
+            except (IOError, PermissionError):
+                pass
+
+    if not found_issues:
+        print_ok("No hardcoded secrets detected")
+    return not found_issues
+
+
+def run_all(project_root: str, url: str | None, skip: list[str]) -> int:
+    """Run all checklist tiers. Returns number of failures."""
+    failures = 0
+
+    # Priority 1 — Security
+    if "security" not in skip:
+        print_header("Priority 1 — Security")
+        if not check_secrets(project_root):
+            failures += 1
+    else:
+        print_skip("Security tier")
+
+    # Priority 2 — Lint
+    if "lint" not in skip:
+        print_header("Priority 2 — Lint")
+        if not run_check("ESLint", ["npx", "eslint", ".", "--max-warnings=0"], project_root):
+            failures += 1
+        if not run_check("TypeScript", ["npx", "tsc", "--noEmit"], project_root):
+            failures += 1
+    else:
+        print_skip("Lint tier")
+
+    # Priority 3 — Schema
+    if "schema" not in skip:
+        print_header("Priority 3 — Schema")
+        print_skip("Schema check — run manually if you have DB migrations")
+    else:
+        print_skip("Schema tier")
+
+    # Priority 4 — Tests
+    if "tests" not in skip:
+        print_header("Priority 4 — Tests")
+        if not run_check("Test suite", ["npm", "test", "--", "--passWithNoTests"], project_root):
+            failures += 1
+    else:
+        print_skip("Tests tier")
+
+    # Priority 5 — UX
+    if "ux" not in skip:
+        print_header("Priority 5 — UX / Accessibility")
+        print_skip("UX audit — run /preview start then check manually or with Lighthouse")
+    else:
+        print_skip("UX tier")
+
+    # Priority 6 — SEO
+    if "seo" not in skip:
+        print_header("Priority 6 — SEO")
+        print_skip("SEO check — use /ui-ux-pro-max for SEO-sensitive pages")
+    else:
+        print_skip("SEO tier")
+
+    # Priority 7 — Lighthouse / E2E
+    if url and "e2e" not in skip:
+        print_header("Priority 7 — Lighthouse / E2E")
+        if not run_check("Playwright E2E", ["npx", "playwright", "test"], project_root):
+            failures += 1
+    elif not url:
+        print_skip("E2E / Lighthouse — pass --url to enable")
+
+    # ━━━ Summary ━━━
+    print(f"\n{BOLD}━━━ Checklist Summary ━━━{RESET}")
+    if failures == 0:
+        print_ok(f"All checks passed — ready to proceed")
+    else:
+        print_fail(f"{failures} tier(s) failed — fix Critical issues before proceeding")
+
+    return failures
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Tribunal project checklist runner")
+    parser.add_argument("path", help="Project root directory")
+    parser.add_argument("--url", help="Local server URL for Lighthouse/E2E checks", default=None)
+    parser.add_argument("--skip", help="Comma-separated tiers to skip (security,lint,schema,tests,ux,seo,e2e)", default="")
+    args = parser.parse_args()
+
+    project_root = os.path.abspath(args.path)
+    if not os.path.isdir(project_root):
+        print_fail(f"Directory not found: {project_root}")
+        sys.exit(1)
+
+    skip = [s.strip().lower() for s in args.skip.split(",") if s.strip()]
+
+    print(f"{BOLD}Tribunal Checklist — {project_root}{RESET}")
+    failures = run_all(project_root, args.url, skip)
+    sys.exit(1 if failures > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()

package/.agent/scripts/session_manager.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+session_manager.py — Agent session state tracking for multi-conversation work.
+
+Usage:
+  python .agent/scripts/session_manager.py save "working on auth"
+  python .agent/scripts/session_manager.py load
+  python .agent/scripts/session_manager.py show
+  python .agent/scripts/session_manager.py clear
+"""
+
+import os
+import sys
+import json
+from pathlib import Path
+from datetime import datetime
+
+STATE_FILE = ".agent_session.json"
+
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+BLUE   = "\033[94m"
+RED    = "\033[91m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+VALID_COMMANDS = {"save", "load", "show", "clear"}
+
+
+def load_state() -> dict:
+    path = Path(STATE_FILE)
+    if not path.exists():
+        return {}
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return {}
+
+
+def save_state(state: dict) -> None:
+    with open(STATE_FILE, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def cmd_save(note: str) -> None:
+    state = load_state()
+    entry = {
+        "timestamp": datetime.now().isoformat(),
+        "note": note,
+        "session": len(state.get("history", [])) + 1,
+    }
+    state.setdefault("history", []).append(entry)
+    state["current"] = entry
+    save_state(state)
+    print(f"{GREEN}✅ Session saved:{RESET} {note}")
+    print(f"   Time:    {entry['timestamp']}")
+    print(f"   Session: #{entry['session']}")
+
+
+def cmd_load() -> None:
+    state = load_state()
+    current = state.get("current")
+    if not current:
+        print(f"{YELLOW}No active session — use 'save' first.{RESET}")
+        return
+    print(f"{BOLD}Current session:{RESET}")
+    print(f"  Session: #{current['session']}")
+    print(f"  Time:    {current['timestamp']}")
+    print(f"  Note:    {current['note']}")
+
+
+def cmd_show() -> None:
+    state = load_state()
+    history = state.get("history", [])
+    if not history:
+        print(f"{YELLOW}No session history.{RESET}")
+        return
+    print(f"{BOLD}Session History ({len(history)} total):{RESET}")
+    for entry in reversed(history[-10:]):
+        print(f"\n  {BLUE}#{entry['session']}{RESET} — {entry['timestamp'][:16]}")
+        print(f"  {entry['note']}")
+
+
+def cmd_clear() -> None:
+    path = Path(STATE_FILE)
+    if path.exists():
+        path.unlink()
+        print(f"{GREEN}✅ Session state cleared.{RESET}")
+    else:
+        print(f"{YELLOW}No session file found — nothing to clear.{RESET}")
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print(f"Usage: session_manager.py [save <note>|load|show|clear]")
+        sys.exit(1)
+
+    cmd = sys.argv[1].lower()
+
+    if cmd not in VALID_COMMANDS:
+        print(f"{RED}Unknown command: '{cmd}'{RESET}")
+        print(f"Valid commands: {', '.join(sorted(VALID_COMMANDS))}")
+        sys.exit(1)
+
+    if cmd == "save":
+        note = " ".join(sys.argv[2:]).strip()
+        if not note:
+            note = f"session {datetime.now().strftime('%Y-%m-%d %H:%M')}"
+        cmd_save(note)
+    elif cmd == "load":
+        cmd_load()
+    elif cmd == "show":
+        cmd_show()
+    elif cmd == "clear":
+        cmd_clear()
+
+
+if __name__ == "__main__":
+    main()

package/.agent/scripts/verify_all.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+verify_all.py — Full pre-deploy validation suite for the Tribunal Agent Kit.
+
+Runs comprehensive checks before any production deployment.
+
+Usage:
+  python .agent/scripts/verify_all.py
+  python .agent/scripts/verify_all.py --skip build,deps
+"""
+
+import os
+import sys
+import subprocess
+import argparse
+from pathlib import Path
+
+RED    = "\033[91m"
+GREEN  = "\033[92m"
+YELLOW = "\033[93m"
+BLUE   = "\033[94m"
+BOLD   = "\033[1m"
+RESET  = "\033[0m"
+
+RESULTS: list[tuple[str, bool, str]] = []
+
+
+def section(title: str) -> None:
+    print(f"\n{BOLD}{BLUE}━━━ {title} ━━━{RESET}")
+
+
+def ok(label: str, note: str = "") -> None:
+    msg = f"{GREEN}✅ {label}{RESET}" + (f"  {YELLOW}({note}){RESET}" if note else "")
+    print(f"  {msg}")
+    RESULTS.append((label, True, note))
+
+
+def fail(label: str, note: str = "") -> None:
+    note_str = f"\n     {note}" if note else ""
+    print(f"  {RED}❌ {label}{RESET}{note_str}")
+    RESULTS.append((label, False, note))
+
+
+def skip(label: str, reason: str) -> None:
+    print(f"  {YELLOW}⏭️  {label} — {reason}{RESET}")
+    RESULTS.append((label, True, f"skipped: {reason}"))
+
+
+def run(label: str, cmd: list[str], cwd: str) -> bool:
+    try:
+        result = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, timeout=120)
+        if result.returncode == 0:
+            ok(label)
+            return True
+        output = (result.stdout + result.stderr).strip()
+        fail(label, output[:500] if output else "non-zero exit code")
+        return False
+    except FileNotFoundError:
+        skip(label, "tool not installed — skipping")
+        return True
+    except subprocess.TimeoutExpired:
+        fail(label, "timed out after 120s")
+        return False
+
+
+def scan_secrets(cwd: str) -> bool:
+    """Scan source files for obviously hardcoded credentials."""
+    patterns = ["password=", "secret=", "api_key=", "private_key=", "auth_token="]
+    found = []
+    for root, dirs, files in os.walk(cwd):
+        dirs[:] = [d for d in dirs if d not in {"node_modules", ".git", "dist", "__pycache__", ".agent"}]
+        for fname in files:
+            if not fname.endswith((".ts", ".js", ".tsx", ".jsx", ".py")):
+                continue
+            fpath = os.path.join(root, fname)
+            try:
+                with open(fpath, encoding="utf-8", errors="ignore") as f:
+                    for i, line in enumerate(f, 1):
+                        low = line.lower().strip()
+                        if any(p in low for p in patterns) and not low.startswith("#") and "=" in low:
+                            rel = os.path.relpath(fpath, cwd)
+                            found.append(f"{rel}:{i}")
+            except (IOError, PermissionError):
+                pass
+    if found:
+        fail("Secret scan", "\n     ".join(found[:5]))
+        return False
+    ok("Secret scan — no hardcoded credentials found")
+    return True
+
+
+def has_npm(cwd: str) -> bool:
+    """Check if there's a package.json to run npm commands against."""
+    return Path(cwd, "package.json").exists()
+
+
+def verify_all(cwd: str, skipped: list[str]) -> int:
+    failures = 0
+
+    section("1 — Secret Scan")
+    if "secrets" not in skipped:
+        if not scan_secrets(cwd):
+            failures += 1
+    else:
+        skip("Secret scan", "skipped by flag")
+
+    section("2 — TypeScript")
+    if "typescript" not in skipped:
+        if has_npm(cwd):
+            if not run("tsc --noEmit", ["npx", "tsc", "--noEmit"], cwd):
+                failures += 1
+        else:
+            skip("TypeScript", "no package.json found in project")
+    else:
+        skip("TypeScript", "skipped by flag")
+
+    section("3 — ESLint")
+    if "lint" not in skipped:
+        if has_npm(cwd):
+            if not run("ESLint", ["npx", "eslint", ".", "--max-warnings=0"], cwd):
+                failures += 1
+        else:
+            skip("ESLint", "no package.json found in project")
+    else:
+        skip("ESLint", "skipped by flag")
+
+    section("4 — Unit Tests")
+    if "tests" not in skipped:
+        if has_npm(cwd):
+            if not run("Test suite", ["npm", "test", "--", "--passWithNoTests"], cwd):
+                failures += 1
+        else:
+            skip("Tests", "no package.json found in project")
+    else:
+        skip("Tests", "skipped by flag")
+
+    section("5 — Build")
+    if "build" not in skipped:
+        if has_npm(cwd):
+            if not run("npm run build", ["npm", "run", "build"], cwd):
+                failures += 1
+        else:
+            skip("Build", "no package.json found in project")
+    else:
+        skip("Build", "skipped by flag")
+
+    section("6 — Dependency Audit")
+    if "deps" not in skipped:
+        if has_npm(cwd):
+            if not run("npm audit", ["npm", "audit", "--audit-level=high"], cwd):
+                failures += 1
+        else:
+            skip("Dependency audit", "no package.json found in project")
+    else:
+        skip("Dependency audit", "skipped by flag")
+
+    print(f"\n{BOLD}━━━ Summary ━━━{RESET}")
+    for label, passed, note in RESULTS:
+        status = f"{GREEN}✅{RESET}" if passed else f"{RED}❌{RESET}"
+        note_str = f"  {YELLOW}({note}){RESET}" if not passed and note else ""
+        print(f"  {status} {label}{note_str}")
+
+    print()
+    if failures == 0:
+        print(f"{GREEN}{BOLD}All checks passed — safe to deploy.{RESET}")
+    else:
+        print(f"{RED}{BOLD}{failures} check(s) failed — fix before deploying.{RESET}")
+
+    return failures
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Tribunal pre-deploy validation suite",
+        usage="%(prog)s [--skip CHECKS]"
+    )
+    parser.add_argument(
+        "--skip",
+        default="",
+        help="Comma-separated checks to skip: secrets,typescript,lint,tests,build,deps"
+    )
+    args = parser.parse_args()
+
+    cwd = os.getcwd()
+    skipped = [s.strip().lower() for s in args.skip.split(",") if s.strip()]
+
+    print(f"{BOLD}Tribunal — verify_all.py{RESET}")
+    print(f"Project: {cwd}\n")
+
+    failures = verify_all(cwd, skipped)
+    sys.exit(1 if failures > 0 else 0)
+
+
+if __name__ == "__main__":
+    main()