@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/scripts/auto_preview.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""
+Auto Preview - OpenCode kit
+==============================
+Manages (start/stop/status) the local development server for previewing the application.
+
+Usage:
+    python .opencode/scripts/auto_preview.py start [port]
+    python .opencode/scripts/auto_preview.py stop
+    python .opencode/scripts/auto_preview.py status
+"""
+
+import os
+import sys
+import time
+import json
+import signal
+import argparse
+import subprocess
+from pathlib import Path
+
+# Detect agent directory name dynamically
+AGENT_DIR = Path(".agents") if Path(".agents").exists() else Path(".agents")
+PID_FILE = AGENT_DIR / "preview.pid"
+LOG_FILE = AGENT_DIR / "preview.log"
+
+def get_project_root():
+    return Path(".").resolve()
+
+def is_running(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+
+def get_start_command(root):
+    pkg_file = root / "package.json"
+    if not pkg_file.exists():
+        return None
+    
+    with open(pkg_file, 'r') as f:
+        data = json.load(f)
+    
+    scripts = data.get("scripts", {})
+    if "dev" in scripts:
+        return ["npm", "run", "dev"]
+    elif "start" in scripts:
+        return ["npm", "start"]
+    return None
+
+def start_server(port=3000):
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                print(f"⚠️  Preview already running (PID: {pid})")
+                return
+        except:
+            pass # Invalid PID file
+
+    root = get_project_root()
+    cmd = get_start_command(root)
+    
+    if not cmd:
+        print("❌ No 'dev' or 'start' script found in package.json")
+        sys.exit(1)
+    
+    # Add port env var if needed (simple heuristic)
+    env = os.environ.copy()
+    env["PORT"] = str(port)
+    
+    print(f"🚀 Starting preview on port {port}...")
+    
+    with open(LOG_FILE, "w") as log:
+        process = subprocess.Popen(
+            cmd,
+            cwd=str(root),
+            stdout=log,
+            stderr=log,
+            env=env,
+            shell=True # Required for npm on windows often, or consistent path handling
+        )
+    
+    PID_FILE.write_text(str(process.pid))
+    print(f"✅ Preview started! (PID: {process.pid})")
+    print(f"   Logs: {LOG_FILE}")
+    print(f"   URL: http://localhost:{port}")
+
+def stop_server():
+    if not PID_FILE.exists():
+        print("ℹ️  No preview server found.")
+        return
+
+    try:
+        pid = int(PID_FILE.read_text().strip())
+        if is_running(pid):
+            # Try gentle kill first
+            os.kill(pid, signal.SIGTERM) if sys.platform != 'win32' else subprocess.call(['taskkill', '/F', '/T', '/PID', str(pid)])
+            print(f"🛑 Preview stopped (PID: {pid})")
+        else:
+            print("ℹ️  Process was not running.")
+    except Exception as e:
+        print(f"❌ Error stopping server: {e}")
+    finally:
+        if PID_FILE.exists():
+            PID_FILE.unlink()
+
+def status_server():
+    running = False
+    pid = None
+    url = "Unknown"
+    
+    if PID_FILE.exists():
+        try:
+            pid = int(PID_FILE.read_text().strip())
+            if is_running(pid):
+                running = True
+                # Heuristic for URL, strictly we should save it
+                url = "http://localhost:3000" 
+        except:
+            pass
+            
+    print("\n=== Preview Status ===")
+    if running:
+        print(f"✅ Status: Running")
+        print(f"🔢 PID: {pid}")
+        print(f"🌐 URL: {url} (Likely)")
+        print(f"📝 Logs: {LOG_FILE}")
+    else:
+        print("⚪ Status: Stopped")
+    print("===================\n")
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=["start", "stop", "status"])
+    parser.add_argument("port", nargs="?", default="3000")
+    
+    args = parser.parse_args()
+    
+    if args.action == "start":
+        start_server(int(args.port))
+    elif args.action == "stop":
+        stop_server()
+    elif args.action == "status":
+        status_server()
+
+if __name__ == "__main__":
+    main()

package/kit/.opencode/scripts/checklist.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Run the fast OpenCode kit validation checklist."""
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+from pathlib import Path
+
+from validation_runner import (
+    CONSOLE,
+    CheckSpec,
+    execute_suite,
+    locate_toolkit_root,
+    print_summary,
+    write_report,
+)
+
+CORE_CHECKS = (
+    CheckSpec(
+        "Security Scan",
+        "skills/vulnerability-scanner/scripts/security_scan.py",
+        "P0 Security",
+        required=True,
+        args=("--output", "summary", "--fail-on", "high"),
+    ),
+    CheckSpec("Lint Check", "skills/lint-and-validate/scripts/lint_runner.py", "P1 Code Quality", required=True),
+    CheckSpec("Type Coverage", "skills/lint-and-validate/scripts/type_coverage.py", "P1 Code Quality"),
+    CheckSpec("Schema Validation", "skills/database-design/scripts/schema_validator.py", "P2 Data Layer"),
+    CheckSpec("Test Runner", "skills/testing-patterns/scripts/test_runner.py", "P3 Testing"),
+    CheckSpec("UX Audit", "skills/frontend-design/scripts/ux_audit.py", "P4 UX & Accessibility"),
+    CheckSpec("Accessibility Check", "skills/frontend-design/scripts/accessibility_checker.py", "P4 UX & Accessibility"),
+    CheckSpec("SEO Check", "skills/seo-fundamentals/scripts/seo_checker.py", "P5 SEO"),
+)
+
+URL_CHECKS = (
+    CheckSpec("Lighthouse Audit", "skills/performance-profiling/scripts/lighthouse_audit.py", "P6 Runtime Checks", target="url", required=True, timeout=180),
+    CheckSpec("Playwright Smoke Test", "skills/webapp-testing/scripts/playwright_runner.py", "P6 Runtime Checks", target="url", timeout=120),
+)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the fast OpenCode kit validation checklist")
+    parser.add_argument("project", nargs="?", default=".", help="Project path to validate")
+    parser.add_argument("--url", help="Running application URL for Lighthouse and Playwright")
+    parser.add_argument("--skip-runtime", action="store_true", help="Skip URL-based runtime checks")
+    parser.add_argument("--stop-on-fail", action="store_true", help="Stop after the first failed check")
+    parser.add_argument("--report", type=Path, help="Write a machine-readable JSON report")
+    args = parser.parse_args()
+
+    project = Path(args.project).resolve()
+    if not project.is_dir():
+        parser.error(f"Project directory does not exist: {project}")
+
+    try:
+        toolkit_root = locate_toolkit_root(project, __file__)
+    except FileNotFoundError as exc:
+        parser.error(str(exc))
+
+    started = datetime.now(timezone.utc)
+    CONSOLE.header("AG KIT - FAST CHECKLIST")
+    print(f"Project: {project}\nToolkit: {toolkit_root}\nURL: {args.url or 'not provided'}")
+
+    specs = list(CORE_CHECKS)
+    if not args.skip_runtime:
+        specs.extend(URL_CHECKS)
+    results = execute_suite(specs, toolkit_root, project, args.url, args.stop_on_fail)
+    success = print_summary("CHECKLIST SUMMARY", results, started)
+    if args.report:
+        write_report(args.report.resolve(), project, toolkit_root, results, started)
+        print(f"Report: {args.report.resolve()}")
+    return 0 if success else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/kit/.opencode/scripts/component_registry.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Build deterministic AG Kit component and runtime metadata."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover
+    yaml = None
+
+SEMVER_RE = re.compile(r"^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$")
+
+
+def extract_frontmatter(path: Path) -> str:
+    text = path.read_text("utf-8", errors="replace")
+    if not text.startswith("---\n"):
+        raise ValueError(f"Missing YAML frontmatter: {path}")
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        raise ValueError(f"Unterminated YAML frontmatter: {path}")
+    return text[4:end]
+
+
+def _fallback_frontmatter(raw: str) -> dict[str, Any]:
+    data: dict[str, Any] = {}
+    for line in raw.splitlines():
+        if not line or line[0].isspace() or line.lstrip().startswith("#"):
+            continue
+        match = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
+        if match:
+            key, value = match.groups()
+            data[key] = value.strip().strip('"\'')
+    return data
+
+
+def load_frontmatter(path: Path) -> dict[str, Any]:
+    raw = extract_frontmatter(path)
+    if yaml is not None:
+        loaded = yaml.safe_load(raw)
+        if not isinstance(loaded, dict):
+            raise ValueError(f"Frontmatter must be a mapping: {path}")
+        return dict(loaded)
+    return _fallback_frontmatter(raw)
+
+
+def normalize_list(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    if isinstance(value, str):
+        return [item.strip() for item in value.split(",") if item.strip()]
+    return []
+
+
+def is_semver(value: object) -> bool:
+    return isinstance(value, str) and SEMVER_RE.fullmatch(value) is not None
+
+
+def compatible_range(version: str) -> str:
+    match = SEMVER_RE.fullmatch(version)
+    if not match:
+        raise ValueError(f"Invalid SemVer: {version}")
+    return version if int(match.group(1)) == 0 else f"^{version}"
+
+
+def version_satisfies(version: str, constraint: str) -> bool:
+    match = SEMVER_RE.fullmatch(version)
+    if not match:
+        return False
+    current = tuple(int(match.group(i)) for i in range(1, 4))
+    if constraint.startswith("^"):
+        base_match = SEMVER_RE.fullmatch(constraint[1:])
+        if not base_match:
+            return False
+        base = tuple(int(base_match.group(i)) for i in range(1, 4))
+        if base[0] > 0:
+            return current >= base and current[0] == base[0]
+        if base[1] > 0:
+            return current >= base and current[:2] == base[:2]
+        return current == base
+    return constraint == version
+
+
+def _relative(root: Path, path: Path) -> str:
+    return path.relative_to(root).as_posix()
+
+
+def _runtime_manifest(root: Path) -> dict[str, Any]:
+    path = root / "antigravity.json"
+    if not path.is_file():
+        raise ValueError("Missing Antigravity runtime contract: antigravity.json")
+    data = json.loads(path.read_text("utf-8"))
+    if data.get("runtime") != "antigravity":
+        raise ValueError("antigravity.json runtime must be 'antigravity'")
+    return {
+        "path": "antigravity.json",
+        "schemaVersion": data.get("schemaVersion"),
+        "requiredCliCommands": data.get("requiredCliCommands", []),
+        "phases": data.get("phases", {}),
+    }
+
+
+def build_manifest(root: Path) -> dict[str, Any]:
+    root = root.resolve()
+    kit_version = (root / "VERSION").read_text("utf-8").strip()
+
+    skills: dict[str, dict[str, Any]] = {}
+    for path in sorted((root / "skills").glob("*/SKILL.md")):
+        data = load_frontmatter(path)
+        name = path.parent.name
+        version = str(data.get("version", ""))
+        skills[name] = {
+            "path": _relative(root, path),
+            "version": version,
+            "allowedTools": normalize_list(data.get("allowed-tools")),
+            "scripts": sorted(_relative(root, item) for item in path.parent.glob("scripts/*.py")),
+        }
+
+    agents: dict[str, dict[str, Any]] = {}
+    for path in sorted((root / "agent").glob("*.md")):
+        data = load_frontmatter(path)
+        dependencies: dict[str, str] = {}
+        for skill_name in normalize_list(data.get("skills")):
+            skill_version = str(skills.get(skill_name, {}).get("version", "0.0.0"))
+            dependencies[skill_name] = compatible_range(skill_version) if is_semver(skill_version) else skill_version
+        agents[path.stem] = {
+            "path": _relative(root, path),
+            "version": str(data.get("version", "")),
+            "model": str(data.get("model", "inherit")),
+            "tools": normalize_list(data.get("tools")),
+            "requires": {"skills": dependencies},
+        }
+
+    workflows: dict[str, dict[str, Any]] = {}
+    for path in sorted((root / "workflows").glob("*.md")):
+        data = load_frontmatter(path)
+        workflows[path.stem] = {
+            "path": _relative(root, path),
+            "version": str(data.get("version", "")),
+            "requires": {
+                "agents": normalize_list(data.get("requires_agents")),
+                "skills": normalize_list(data.get("requires_skills")),
+            },
+            "artifactOutputs": normalize_list(data.get("artifact_outputs")),
+        }
+
+    rules: dict[str, dict[str, Any]] = {}
+    for path in sorted((root / "rules").glob("*.md")):
+        data = load_frontmatter(path)
+        rules[path.stem] = {
+            "path": _relative(root, path),
+            "version": str(data.get("version", "")),
+            "priority": str(data.get("priority", "")),
+            "trigger": str(data.get("trigger", "")),
+        }
+
+    return {
+        "$schema": "schemas/manifest.schema.json",
+        "schemaVersion": "1.0.0",
+        "kitVersion": kit_version,
+        "contracts": {
+            "antigravityRuntime": "1.0.0",
+            "componentApi": "1.0.0",
+            "memorySchema": "1.0.0",
+            "rulesApi": "1.0.0",
+            "workflowApi": "1.0.0",
+        },
+        "support": {
+            "primary": "Google Antigravity",
+            "official": ["Google Antigravity"],
+            "bestEffort": ["Gemini CLI", "other Markdown-compatible agent tools"],
+            "portableFormat": True,
+        },
+        "runtimes": {"antigravity": _runtime_manifest(root)},
+        "agents": agents,
+        "skills": skills,
+        "workflows": workflows,
+        "rules": rules,
+    }
+
+
+def canonical_json(data: object) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=False, sort_keys=True) + "\n"
+
+
+def component_files(root: Path) -> list[Path]:
+    """Return every managed source file covered by the integrity lock."""
+    root = root.resolve()
+    files: list[Path] = []
+    for name in (
+        "VERSION",
+        "README.md",
+        "ARCHITECTURE.md",
+        "CHANGELOG.md",
+        "antigravity.json",
+        "hooks.json",
+        "mcp_config.json",
+    ):
+        path = root / name
+        if path.is_file():
+            files.append(path)
+    for directory in ("agent", "skills", "workflows", "rules", "memory", "hooks", "schemas", "scripts"):
+        base = root / directory
+        if not base.is_dir():
+            continue
+        for path in base.rglob("*"):
+            if not path.is_file() or "__pycache__" in path.parts or path.suffix == ".pyc":
+                continue
+            files.append(path)
+    return sorted({path.resolve() for path in files})
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_lock(root: Path, manifest: dict[str, Any]) -> dict[str, Any]:
+    root = root.resolve()
+    hashes = {
+        path.relative_to(root).as_posix(): sha256_file(path)
+        for path in component_files(root)
+        if path.name != "manifest.lock.json"
+    }
+    return {
+        "$schema": "schemas/manifest-lock.schema.json",
+        "schemaVersion": "1.0.0",
+        "kitVersion": manifest["kitVersion"],
+        "manifestSha256": hashlib.sha256(canonical_json(manifest).encode("utf-8")).hexdigest(),
+        "components": hashes,
+    }

package/kit/.opencode/scripts/dependency_graph.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Generate a maintainable Mermaid dependency graph from manifest.json."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from component_registry import build_manifest
+
+
+def node_id(prefix: str, name: str) -> str:
+    return prefix + "_" + name.replace("-", "_")
+
+
+def render(root: Path) -> str:
+    manifest = build_manifest(root)
+    lines = [
+        "# AG Kit Dependency Graph",
+        "",
+        "> Generated by `.opencode/scripts/dependency_graph.py`. Do not edit manually.",
+        "",
+        f"Kit version: `{manifest['kitVersion']}` · {len(manifest['agents'])} agents · {len(manifest['skills'])} skills · {len(manifest['workflows'])} workflows",
+        "",
+        "```mermaid",
+        "flowchart LR",
+        "  subgraph Workflows",
+    ]
+    for name in manifest["workflows"]:
+        lines.append(f'    {node_id("W", name)}["/{name}"]')
+    lines.extend(["  end", "  subgraph Agents"])
+    for name in manifest["agents"]:
+        lines.append(f'    {node_id("A", name)}["{name}"]')
+    lines.extend(["  end", "  subgraph Skills"])
+    for name in manifest["skills"]:
+        lines.append(f'    {node_id("S", name)}["{name}"]')
+    lines.append("  end")
+
+    for workflow, data in manifest["workflows"].items():
+        for agent in data["requires"]["agents"]:
+            lines.append(f"  {node_id('W', workflow)} --> {node_id('A', agent)}")
+        for skill in data["requires"]["skills"]:
+            lines.append(f"  {node_id('W', workflow)} -.-> {node_id('S', skill)}")
+    for agent, data in manifest["agents"].items():
+        for skill in data["requires"]["skills"]:
+            lines.append(f"  {node_id('A', agent)} --> {node_id('S', skill)}")
+    lines.extend(["```", "", "## Contracts", ""])
+    for key, value in manifest["contracts"].items():
+        lines.append(f"- `{key}`: `{value}`")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate AG Kit dependency graph")
+    parser.add_argument("path", nargs="?", default=None, help="Path to .agents")
+    parser.add_argument("--check", action="store_true", help="Fail when DEPENDENCY_GRAPH.md is stale")
+    args = parser.parse_args()
+    root = Path(args.path).resolve() if args.path else Path(__file__).resolve().parents[1]
+    output = root / "DEPENDENCY_GRAPH.md"
+    expected = render(root)
+    if args.check:
+        if not output.is_file() or output.read_text("utf-8") != expected:
+            print("DEPENDENCY_GRAPH.md is stale")
+            return 1
+        print("Dependency graph is synchronized.")
+        return 0
+    output.write_text(expected, "utf-8")
+    print(f"Wrote {output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/kit/.opencode/scripts/generate_manifest.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Generate or verify the AG Kit component registry and lock file."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from component_registry import build_lock, build_manifest, canonical_json
+
+
+def check_file(path: Path, expected: str) -> bool:
+    return path.is_file() and path.read_text("utf-8") == expected
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Generate AG Kit manifest.json and manifest.lock.json")
+    parser.add_argument("path", nargs="?", default=None, help="Path to .agents")
+    parser.add_argument("--check", action="store_true", help="Fail when generated files are stale")
+    args = parser.parse_args()
+
+    root = Path(args.path).resolve() if args.path else Path(__file__).resolve().parents[1]
+    manifest = build_manifest(root)
+    manifest_text = canonical_json(manifest)
+    lock = build_lock(root, manifest)
+    lock_text = canonical_json(lock)
+    outputs = [(root / "manifest.json", manifest_text), (root / "manifest.lock.json", lock_text)]
+
+    if args.check:
+        stale = [path.name for path, expected in outputs if not check_file(path, expected)]
+        if stale:
+            print("Stale generated registry files: " + ", ".join(stale))
+            return 1
+        print("Component registry is synchronized.")
+        return 0
+
+    for path, content in outputs:
+        path.write_text(content, "utf-8")
+        print(f"Wrote {path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())