@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/router.py

@@ -0,0 +1,232 @@
+"""Command routing to Python orchestrators.
+
+Routes commands to appropriate orchestrators via uv run.
+"""
+
+import glob
+import os
+import subprocess
+import tomllib
+from pathlib import Path
+
+ORCHESTRATORS = {
+    "jira": {
+        "module": "vds_jira_orchestrator.cli",
+        "path": "jira_orchestrator",
+        "entry": "vds-jira-cli",
+    },
+    "confluence": {
+        "module": "confluence_orchestrator.cli",
+        "path": "confluence_orchestrator",
+        "entry": "vds-confluence-cli",
+    },
+    "bitbucket": {
+        "module": "vds_bitbucket_orchestrator.cli",
+        "path": "bitbucket_orchestrator",
+        "entry": "vds-bitbucket-cli",
+    },
+    "git": {
+        "module": "vds_git_orchestrator.cli",
+        "path": "git_orchestrator",
+        "entry": "vds-git-orchestrator",
+    },
+    "pdf": {
+        "module": "vds_pdf_orchestrator.cli",
+        "path": "pdf_orchestrator",
+        "entry": "vds-pdf",
+    },
+    "excel": {
+        "module": "vds_excel_orchestrator.cli",
+        "path": "excel_orchestrator",
+        "entry": "vds-excel",
+    },
+    "google_sheets": {
+        "module": "vds_google_sheets_orchestrator.cli",
+        "path": "google_sheets_orchestrator",
+        "entry": "vds-google-sheets-cli",
+    },
+    "elastic": {
+        "module": "vds_elastic_orchestrator.cli",
+        "path": "elastic_orchestrator",
+        "entry": "vds-elastic",
+    },
+    "grafana": {
+        "module": "vds_grafana_orchestrator.cli",
+        "path": "grafana_orchestrator",
+        "entry": "vds-grafana",
+    },
+    "sonarqube": {
+        "module": "vds_sonarqube_orchestrator.cli",
+        "path": "sonarqube_orchestrator",
+        "entry": "vds-sonarqube",
+    },
+    "brd": {
+        "module": "vds_brd_orchestrator.cli",
+        "path": "brd_orchestrator",
+        "entry": "vds-brd",
+    },
+    "markdown": {
+        "module": "vds_markdown_orchestrator.cli",
+        "path": "markdown_orchestrator",
+        "entry": "vds-markdown",
+    },
+    "mcp": {
+        "module": "vds_mcp_server.cli",
+        "path": "mcp_server",
+        "entry": "vds-mcp-server",
+    },
+    "vidp": {
+        "module": "vds_vidp_orchestrator.cli",
+        "path": "vidp_orchestrator",
+        "entry": "vds-vidp",
+    },
+}
+
+
+def _project_scripts(project_dir: Path) -> set[str]:
+    pyproject_path = project_dir / "pyproject.toml"
+    if not pyproject_path.exists():
+        raise FileNotFoundError(f"pyproject.toml not found for orchestrator: {project_dir}")
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    scripts = data.get("project", {}).get("scripts", {})
+    if isinstance(scripts, dict):
+        return set(scripts.keys())
+    return set()
+
+
+def _script_target(project_dir: Path, entry: str) -> str | None:
+    pyproject_path = project_dir / "pyproject.toml"
+    if not pyproject_path.exists():
+        return None
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    scripts = data.get("project", {}).get("scripts", {})
+    if not isinstance(scripts, dict):
+        return None
+    target = scripts.get(entry)
+    return target if isinstance(target, str) else None
+
+
+def _target_module_exists(project_dir: Path, target: str) -> bool:
+    """Check if a module target exists.
+
+    Handles two layouts:
+    - src-layout: project/src/<package>/...  (jira_orchestrator, confluence_orchestrator)
+    - root-layout: project/<package>/...      (vds_evolution — package at project root)
+
+    For root-layout packages, the package directory name itself is stripped from
+    the module path before the lookup, so "vds_evolution.cli" resolves to
+    project_dir/cli.py (not project_dir/vds_evolution/cli.py).
+    """
+    module_path = target.split(":", 1)[0].strip()
+    if not module_path:
+        return False
+
+    parts = module_path.split(".")
+    parts[0]
+
+    # Root-level lookup: package lives directly under project_dir
+    # Strip the top-level package so "vds_evolution.cli" → project_dir/cli.py
+    relative_parts = parts[1:] if len(parts) >= 2 else parts
+
+    root_module_file = project_dir / Path(*relative_parts)
+    root_py_file = root_module_file.with_suffix(".py")
+    root_package_init = root_module_file / "__init__.py"
+    if root_py_file.exists() or root_package_init.exists():
+        return True
+
+    # Src-layout lookup (package inside src/)
+    src_dir = project_dir / "src"
+    module_file = src_dir / Path(*parts)
+    py_file = module_file.with_suffix(".py")
+    package_init = module_file / "__init__.py"
+    return py_file.exists() or package_init.exists()
+
+
+def validate_orchestrator(service: str, script_dir: Path) -> tuple[bool, str]:
+    """Validate orchestrator project, entrypoint declaration, and module target."""
+    if service not in ORCHESTRATORS:
+        return False, f"Unknown service: {service}"
+
+    config = ORCHESTRATORS[service]
+    project_dir = script_dir / config["path"]
+    if not project_dir.exists():
+        return False, "❌ Missing project dir"
+
+    pyproject_path = project_dir / "pyproject.toml"
+    if not pyproject_path.exists():
+        return False, "❌ Missing pyproject.toml"
+
+    entry = config.get("entry")
+    if not entry:
+        return True, "✅ Available (module)"
+
+    scripts = _project_scripts(project_dir)
+    if entry not in scripts:
+        return False, f"❌ Missing entry: {entry}"
+
+    target = _script_target(project_dir, entry)
+    if not target:
+        return False, f"❌ Invalid target for entry: {entry}"
+
+    if not _target_module_exists(project_dir, target):
+        return False, f"❌ Broken target module: {target.split(':', 1)[0]}"
+
+    return True, "✅ Available"
+
+
+def run_orchestrator(service: str, args: list[str], script_dir: Path) -> int:
+    """Run orchestrator via uv.
+
+    Args:
+        service: Service name (jira, confluence, bitbucket, git)
+        args: Command arguments to pass to orchestrator
+        script_dir: Base directory containing orchestrators
+
+    Returns:
+        int: Exit code from orchestrator (0 for success)
+
+    Raises:
+        ValueError: If service is not recognized
+
+    Example:
+        >>> exit_code = run_orchestrator("jira", ["search", "project = NTTC"], Path("/path/to/scripts"))
+        >>> if exit_code == 0:
+        ...     print("Success")
+    """
+    if service not in ORCHESTRATORS:
+        raise ValueError(f"Unknown service: {service}. Available: {list(ORCHESTRATORS.keys())}")
+
+    config = ORCHESTRATORS[service]
+    project_dir = script_dir / config["path"]
+
+    if not project_dir.exists():
+        raise FileNotFoundError(f"Orchestrator directory not found: {project_dir}")
+
+    # Use uv to run the orchestrator
+    entry = config.get("entry")
+    if entry:
+        ok, status = validate_orchestrator(service, script_dir)
+        if not ok:
+            raise ValueError(f"Service '{service}' is not runnable: {status}")
+        cmd = ["uv", "run", "--project", str(project_dir), entry, *args]
+    else:
+        cmd = ["uv", "run", "--project", str(project_dir), "python", "-m", config["module"], *args]
+
+    env = os.environ.copy()
+    env.pop("VIRTUAL_ENV", None)
+    orchestrator_src = project_dir / "src"
+    existing_path = env.get("PYTHONPATH", "")
+    if orchestrator_src.exists():
+        env["PYTHONPATH"] = f"{orchestrator_src}{os.pathsep}{existing_path}" if existing_path else str(orchestrator_src)
+    # Also prepend workspace .venv site-packages so orchestrators in worktrees can
+    # resolve shared workspace dependencies (e.g. vds_platform_core) that are not
+    # installed in the orchestrator's own src/ tree.
+    venv_site_packages = glob.glob(str(script_dir / ".venv" / "lib" / "python*" / "site-packages"))
+    if venv_site_packages:
+        current = env.get("PYTHONPATH", "")
+        env["PYTHONPATH"] = f"{venv_site_packages[0]}{os.pathsep}{current}" if current else venv_site_packages[0]
+    # Run from the workspace root so orchestrators with workspace-relative defaults
+    # (for example git_orchestrator's default repo-manifest.yaml) behave consistently
+    # regardless of the caller's current shell directory.
+    result = subprocess.run(cmd, check=False, env=env, cwd=str(script_dir))
+    return result.returncode

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/skills_cmd.py

@@ -0,0 +1,274 @@
+"""vds-cli skills subcommand — delegates to vds-skills-sync package.
+
+Implements TSK-SYNC-050 from .gpt-5.4/specs/vds-skills-sync/tasks.md.
+The vds-skills-sync package lives in a sibling repo (.claude/vds-skills/),
+so we delegate via subprocess rather than importing.
+
+Phase 6 (TSK-SYNC-063 cli half) adds:
+  - sync: --skills, --exclude-skills, --category, --diff, --diff-format
+  - validate: full W2a surface (--skill, --all, --strict, --fix, --output, --json)
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+skills_app = typer.Typer(
+    help=(
+        "Sync VDS skills to AI coding agents (Claude Code, Cursor, Copilot, generic). "
+        "See .gpt-5.4/specs/vds-skills-sync/."
+    )
+)
+
+_VALID_DIFF_FORMATS = frozenset({"summary", "unified", "json"})
+
+
+def _find_vds_skills_sync() -> Path:
+    """Locate the vds-skills-sync package directory.
+
+    Resolution order:
+      1. VDS_SKILLS_SYNC_DIR env var (must contain src/vds_skills_sync/__init__.py).
+      2. Walk up from this file until we find .claude/vds-skills/vds-skills-sync.
+
+    Raises:
+        RuntimeError: When neither resolution strategy locates a valid package.
+    """
+    env_override = os.environ.get("VDS_SKILLS_SYNC_DIR")
+    if env_override:
+        path = Path(env_override)
+        if (path / "src" / "vds_skills_sync" / "__init__.py").exists():
+            return path
+        raise RuntimeError(f"VDS_SKILLS_SYNC_DIR={env_override} does not contain src/vds_skills_sync/__init__.py")
+    for parent in Path(__file__).resolve().parents:
+        candidate = parent / "claude" / "vds-skills" / "vds-skills-sync"
+        if (candidate / "src" / "vds_skills_sync" / "__init__.py").exists():
+            return candidate
+    raise RuntimeError(
+        "vds-skills-sync package not found. Set VDS_SKILLS_SYNC_DIR or run from a VDS monorepo checkout."
+    )
+
+
+def _run_vds_skills_sync(args: list[str]) -> int:
+    """Delegate to `python -m vds_skills_sync` and return its exit code."""
+    package_dir = _find_vds_skills_sync()
+    src_dir = package_dir / "src"
+    env = os.environ.copy()
+    existing = env.get("PYTHONPATH", "")
+    env["PYTHONPATH"] = f"{src_dir}{os.pathsep}{existing}" if existing else str(src_dir)
+    cmd = [sys.executable, "-m", "vds_skills_sync", *args]
+    result = subprocess.run(cmd, env=env, cwd=str(package_dir), check=False)
+    return result.returncode
+
+
+@skills_app.command("sync")
+def sync(
+    agent: Annotated[
+        str,
+        typer.Option(
+            "--agent",
+            "-a",
+            help="Target agent: claude|cursor|copilot|generic|all",
+        ),
+    ] = "claude",
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Preview without modifying files."),
+    ] = False,
+    force: Annotated[
+        bool,
+        typer.Option("--force", help="Skip validation checks before sync."),
+    ] = False,
+    scope: Annotated[
+        str,
+        typer.Option(
+            "--scope",
+            help="Installation scope: project|user (affects Cursor).",
+        ),
+    ] = "project",
+    skills: Annotated[
+        str,
+        typer.Option(
+            "--skills",
+            help=("Comma-separated skill names to sync. Mutually exclusive with --exclude-skills."),
+        ),
+    ] = "",
+    exclude_skills: Annotated[
+        str,
+        typer.Option(
+            "--exclude-skills",
+            help=("Comma-separated skill names to exclude from sync. Mutually exclusive with --skills."),
+        ),
+    ] = "",
+    category: Annotated[
+        str,
+        typer.Option(
+            "--category",
+            help="Comma-separated categories to filter skills.",
+        ),
+    ] = "",
+    diff: Annotated[
+        bool,
+        typer.Option(
+            "--diff",
+            help="Show structured diff (requires --dry-run).",
+        ),
+    ] = False,
+    diff_format: Annotated[
+        str,
+        typer.Option(
+            "--diff-format",
+            help="Diff output format: summary|unified|json (default: summary).",
+        ),
+    ] = "summary",
+) -> None:
+    """Sync VDS skills to an AI agent."""
+    if skills and exclude_skills:
+        raise typer.BadParameter(
+            "--skills and --exclude-skills are mutually exclusive.",
+            param_hint="'--skills' / '--exclude-skills'",
+        )
+    if diff_format not in _VALID_DIFF_FORMATS:
+        raise typer.BadParameter(
+            f"Invalid diff format '{diff_format}'. Choose one of: {', '.join(sorted(_VALID_DIFF_FORMATS))}.",
+            param_hint="'--diff-format'",
+        )
+
+    args: list[str] = ["--agent", agent, "--scope", scope]
+    if dry_run:
+        args.append("--dry-run")
+    if force:
+        args.append("--force")
+    if skills:
+        args += ["--skills", skills]
+    if exclude_skills:
+        args += ["--exclude-skills", exclude_skills]
+    if category:
+        args += ["--category", category]
+    if diff:
+        args.append("--diff")
+    if diff_format != "summary":
+        args += ["--diff-format", diff_format]
+    elif diff:
+        # Explicitly pass default so downstream always knows the format.
+        args += ["--diff-format", diff_format]
+    raise typer.Exit(_run_vds_skills_sync(args))
+
+
+@skills_app.command("list")
+def list_skills() -> None:
+    """List all skills from the VDS registry."""
+    raise typer.Exit(_run_vds_skills_sync(["--list"]))
+
+
+@skills_app.command("validate")
+def validate(
+    validate_skill: Annotated[
+        Path | None,
+        typer.Option(
+            "--skill",
+            "--validate-skill",
+            help="Validate a single SKILL.md file by path.",
+        ),
+    ] = None,
+    validate_all: Annotated[
+        bool,
+        typer.Option(
+            "--all",
+            "--validate-all",
+            help="Validate every registry-declared skill (default when no target given).",
+        ),
+    ] = False,
+    strict: Annotated[
+        bool,
+        typer.Option(
+            "--strict",
+            help="Promote quality warnings to errors.",
+        ),
+    ] = False,
+    fix: Annotated[
+        bool,
+        typer.Option(
+            "--fix",
+            help="Auto-correct trivial issues in-place.",
+        ),
+    ] = False,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Write audit report to PATH.",
+        ),
+    ] = None,
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help=(
+                "Output JSON instead of human-readable text. "
+                "Note: JSON output may include header lines on stdout when "
+                "invoked via this CLI wrapper. To extract clean JSON use: "
+                "python -c 'import json,sys; [print(l) for l in sys.stdin "
+                'if l.strip().startswith(("{","["))]\''
+            ),
+        ),
+    ] = False,
+) -> None:
+    """Validate VDS skills against the AgentSkills specification.
+
+    By default validates all registry skills. Use --skill PATH for a single
+    skill file. Exits 0 on clean pass, 1 on validation errors, 2 on strict
+    quality failures (when --strict is set).
+    """
+    if validate_skill and validate_all:
+        raise typer.BadParameter(
+            "Cannot combine --skill and --all.",
+            param_hint="'--skill' / '--all'",
+        )
+
+    args: list[str] = []
+    if validate_skill:
+        args += ["--validate-skill", str(validate_skill)]
+    else:
+        # Default to --validate-all when neither specific target is given.
+        args.append("--validate-all")
+
+    if strict:
+        args.append("--strict")
+    if fix:
+        args.append("--fix")
+    if output:
+        args += ["--output", str(output)]
+    if json_output:
+        args.append("--json")
+
+    raise typer.Exit(_run_vds_skills_sync(args))
+
+
+@skills_app.command("info")
+def info(
+    name: Annotated[
+        str,
+        typer.Argument(help="Skill name, e.g. audit-orchestrator-skill."),
+    ],
+) -> None:
+    """Show a skill's rendered content."""
+    raise typer.Exit(_run_vds_skills_sync(["--read", name]))
+
+
+@skills_app.command("rollback")
+def rollback() -> None:
+    """Restore skills from the most recent backup."""
+    raise typer.Exit(_run_vds_skills_sync(["--rollback"]))
+
+
+@skills_app.command("version")
+def version() -> None:
+    """Show the vds-skills-sync package version."""
+    raise typer.Exit(_run_vds_skills_sync(["--version"]))