@ngocsangairvds/vsaf 3.1.27 → 3.2.1

package/tools/vds-scripts/scripts/verification/phase2_portable_paths_ubuntu_docker.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Phase 2 portable path/config verification on Ubuntu via Docker Compose.
+# This validates the shared helper layer in a real Linux userspace while keeping
+# the checked-out worktree mounted from the host.
+#
+# What this script proves:
+# - explicit VDS env overrides work in Linux containers
+# - platformdirs-backed helper defaults remain importable in Linux
+# - focused Phase 2 tests pass under an Ubuntu image with uv installed
+#
+# What this script does NOT prove:
+# - native Windows execution
+# - Windows container behavior
+# - any host-specific Docker Desktop path quirks beyond this mounted workspace
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+WORKTREE_ROOT="$(cd "$SCRIPT_DIR/.."/.. && pwd)"
+COMPOSE_FILE="$WORKTREE_ROOT/docker/compose.phase2-verification.yml"
+
+mkdir -p "$WORKTREE_ROOT/.phase2-linux/config" "$WORKTREE_ROOT/.phase2-linux/cache" "$WORKTREE_ROOT/.phase2-linux/logs"
+
+docker compose -f "$COMPOSE_FILE" run --rm phase2-ubuntu-verifier
+
+echo "Phase 2 Ubuntu/Docker Compose verification completed successfully."

package/tools/vds-scripts/scripts/worktree_uv.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Run uv in the current worktree without inheriting a mismatched active virtualenv.
+# Usage: scripts/worktree_uv.sh <uv args...>
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+WORKTREE_VENV="${ROOT}/.venv"
+site_packages="$(echo "$WORKTREE_VENV"/lib/python*/site-packages)"
+
+# uv project commands manage their own environment by default.
+# If a parent checkout exported VIRTUAL_ENV from a different repo/worktree,
+# uv will warn and ignore it. Clear inherited active-environment state so
+# worktree commands are quiet and deterministic.
+if [[ -n "${VIRTUAL_ENV:-}" && "${VIRTUAL_ENV}" != "${WORKTREE_VENV}" ]]; then
+  unset VIRTUAL_ENV
+fi
+
+# Prevent a parent shell from forcing a different project environment.
+unset UV_PROJECT_ENVIRONMENT
+unset CONDA_PREFIX
+
+# Worktree venvs in this repo rely on editable _vds_*.pth files. Rebuild
+# PYTHONPATH from those stubs so uv-launched entrypoints resolve workspace
+# packages consistently even when Python skips underscore-prefixed .pth files.
+if [[ -d "$site_packages" ]]; then
+  pythonpath_entries=()
+  while IFS= read -r -d '' pth_file; do
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      [[ -z "$line" ]] && continue
+      pythonpath_entries+=("$line")
+    done < "$pth_file"
+  done < <(find "$site_packages" -maxdepth 1 -type f -name '_vds_*.pth' -print0 | sort -z)
+
+  if [[ ${#pythonpath_entries[@]} -gt 0 ]]; then
+    joined_pythonpath=""
+    for entry in "${pythonpath_entries[@]}"; do
+      if [[ -z "$joined_pythonpath" ]]; then
+        joined_pythonpath="$entry"
+      else
+        joined_pythonpath="$joined_pythonpath:$entry"
+      fi
+    done
+    export PYTHONPATH="$joined_pythonpath${PYTHONPATH:+:$PYTHONPATH}"
+  fi
+fi
+
+exec uv "$@"

package/tools/vds-scripts/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.11"
+
+[[package]]
+name = "vds-scripts-monorepo"
+version = "0.0.0"
+source = { virtual = "." }

package/tools/vds-scripts/vds_cli/README.md

@@ -0,0 +1,126 @@
+# VDS CLI - Cross-Platform Python CLI
+
+Cross-platform Python CLI wrapper for VDS Platform operations.
+
+## Installation (uv-native)
+
+```bash
+cd vds-scripts
+# Optional: prime every project environment (add --frozen or other uv sync flags as needed)
+./scripts/bootstrap_uv.sh --frozen
+
+# Or just sync this package when needed
+uv sync --project vds_cli
+```
+
+> Per the official uv project documentation, `uv run` automatically creates or updates the local `.venv` for the
+> requested project when it executes, so no manual `uv pip install -e` is required. Use `uv sync --project vds_cli` (or
+> the bootstrap script) only when you want to pre-build the environment ahead of time. (Source:
+> [uv docs – The project environment](https://github.com/astral-sh/uv/blob/main/docs/concepts/projects/layout.md#the-project-environment))
+
+## Usage
+
+### Environment Management
+
+```bash
+# Load environment (loads from ~/.vds/.env)
+uv run --project vds_cli vds-cli env load
+
+# Check environment status
+uv run --project vds_cli vds-cli env status
+
+# Check system status (orchestrators + environment)
+uv run --project vds_cli vds-cli status
+```
+
+### Using Orchestrators
+
+```bash
+# JIRA operations
+uv run --project vds_cli vds-cli jira search "project = NTTC" --limit 20
+uv run --project vds_cli vds-cli jira issue NTTC-123
+
+# Confluence operations
+uv run --project vds_cli vds-cli confluence content search "space = TDOV"
+uv run --project vds_cli vds-cli confluence content page 99647801
+
+# Bitbucket operations
+uv run --project vds_cli vds-cli bitbucket projects
+uv run --project vds_cli vds-cli bitbucket repositories
+
+# Git operations
+uv run --project vds_cli vds-cli git clone lep
+uv run --project vds_cli vds-cli git pull --project insurance
+uv run --project vds_cli vds-cli git status --match "*service*"
+```
+
+### Help
+
+```bash
+# Show main help
+uv run --project vds_cli vds-cli --help
+
+# Show command help
+uv run --project vds_cli vds-cli jira --help
+uv run --project vds_cli vds-cli confluence --help
+```
+
+## Features
+
+- ✅ **Cross-platform**: Works on Mac, Linux, and Windows
+- ✅ **Environment Management**: Automatic loading from `~/.vds/.env` using pydantic-settings v2.12.0+
+- ✅ **Unified Interface**: Single CLI for all orchestrators (JIRA, Confluence, Bitbucket, Git)
+- ✅ **Rich Console Output**: Beautiful tables and formatted output
+- ✅ **Type-Safe Configuration**: Full Python type hints and validation
+- ✅ **Quality Assured**: 87% test coverage, zero ruff linting issues
+
+## Migration from Bash CLI
+
+The Python CLI (`vds-cli`) replaces the legacy bash wrapper (now removed). The command interface is identical:
+
+**Before (bash)**:
+
+```bash
+uv run --project vds_cli vds-cli jira search "project = NTTC" 20
+```
+
+**After (Python)**:
+
+```bash
+uv run --project vds_cli vds-cli jira search "project = NTTC" --limit 20
+```
+
+All commands work the same way, with improved error handling and cross-platform support.
+
+## Development
+
+### Running Tests
+
+```bash
+cd vds-scripts/vds_cli
+uv run pytest tests/unit/ -v
+uv run pytest tests/verification/ -v  # Requires credentials
+```
+
+### Code Quality
+
+```bash
+# Lint check
+uv run ruff check src/
+
+# Format code
+uv run ruff format src/
+```
+
+## Requirements
+
+- Python >= 3.11
+- uv (for package management)
+- Environment file at `~/.vds/.env` with credentials
+
+## Dependencies
+
+- **typer** >= 0.20.0 - CLI framework
+- **rich** >= 13.7.0 - Console output
+- **pydantic** >= 2.12.3 - Data validation
+- **pydantic-settings** >= 2.12.0 - Settings management

package/tools/vds-scripts/vds_cli/VERIFICATION_REPORT.md

@@ -0,0 +1,41 @@
+# VDS CLI Verification Report
+
+**Date**: January 10, 2026
+**Status**: ✅ PASSED
+
+## Summary
+
+The VDS CLI (`vds-cli`) has been verified for production readiness. All unit tests passed, and code quality checks (linting) are clean.
+
+## Verification Steps
+
+### 1. Code Quality
+- **Tool**: `ruff`
+- **Result**: ✅ Passed (Zero issues)
+- **Actions**: Fixed trailing whitespace in `cli.py` and `env.py`.
+
+### 2. Unit Tests
+- **Tool**: `pytest`
+- **Coverage**: 77%
+- **Result**: ✅ Passed (19/19 tests)
+- **Fixes**:
+  - Updated `test_cli_git_command` to properly mock `settings` object attributes (avoiding `TypeError`).
+  - Updated `test_run_orchestrator_success` to assert correct entry point usage (`vds-jira-cli`) instead of legacy `python -m` invocation.
+
+### 3. Installation & Environment
+- **Tool**: `uv`
+- **Result**: ✅ Validated dependency sync and virtual environment creation.
+
+## Key Components Verified
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `cli.py` | ✅ | Main entry point, command routing |
+| `router.py` | ✅ | Orchestrator delegation logic |
+| `env.py` | ✅ | Environment variable loading (pydantic-settings) |
+
+## Recommendations
+
+- Maintain `pytest` coverage above 75%.
+- Continue using `uv sync` for dependency management.
+- Ensure `~/.vds/.env` contains valid credentials for integration tests.

package/tools/vds-scripts/vds_cli/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "vds-cli"
+version = "4.0.0"
+description = "Cross-platform VDS Platform CLI"
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.20.0",              # Latest: 0.20.0 (Oct 2025) - Context7: /websites/typer_tiangolo
+    "rich>=13.7.0",               # Latest: 13.7.0+ (Nov 2025)
+    "pydantic>=2.12.3",           # Latest: 2.12.3+ (Oct 2025)
+    "pydantic-settings>=2.12.0",  # Latest: 2.12.0 (Nov 2025) - Context7: /pydantic/pydantic-settings
+]
+
+[project.scripts]
+vds-cli = "vds_cli.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.20.0"]
+build-backend = "hatchling.build"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.1",              # Latest: 9.0.1+ - Context7: /pytest-dev/pytest
+    "pytest-cov>=5.0.0",
+    "ruff>=0.14.5",               # Latest: 0.14.5+ - Context7: /astral-sh/ruff
+]
+
+[tool.uv]
+package = true
+
+[tool.uv.sources]
+vds_cli = { path = "src" }
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.1",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.14.5",
+]

package/tools/vds-scripts/vds_cli/src/vds_cli/__init__.py

@@ -0,0 +1,3 @@
+"""VDS Platform CLI - Cross-platform Python CLI wrapper."""
+
+__version__ = "4.0.0"

package/tools/vds-scripts/vds_cli/src/vds_cli/cli.py

@@ -0,0 +1,173 @@
+"""Main CLI application using Typer.
+
+Based on Typer v0.20.0+ API
+Context7: /websites/typer_tiangolo
+Key Features: typer.Typer(), @app.command(), Annotated options
+"""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from .env import load_environment
+from .router import run_orchestrator
+
+app = typer.Typer(help="VDS Platform CLI - Unified Interface for AI Agents")
+console = Console()
+
+PASS_THRU_CONTEXT = {"allow_extra_args": True, "ignore_unknown_options": True}
+
+# Get scripts directory (parent of vds_cli package)
+SCRIPT_DIR = Path(__file__).resolve().parent.parent.parent.parent
+
+
+@app.command()
+def env(
+    action: str = typer.Argument(..., help="Action: load or status"),
+) -> None:
+    """Environment management."""
+    settings = load_environment()
+
+    if action == "load":
+        console.print("[blue]🔄 Loading VDS environment...[/blue]")
+        if settings.vds_username:
+            console.print("[green]✅ VDS environment loaded successfully.[/green]")
+        else:
+            console.print("[yellow]⚠️  VDS environment file not found at ~/.vds/.env[/yellow]")
+            console.print("[yellow]💡 Create ~/.vds/.env with your credentials[/yellow]")
+
+    elif action == "status":
+        table = Table(title="Environment Status")
+        table.add_column("Variable", style="cyan")
+        table.add_column("Status", style="magenta")
+
+        table.add_row(
+            "Bitbucket Token",
+            "✅ Set" if settings.bitbucket_access_token else "❌ Missing",
+        )
+        table.add_row(
+            "Internal Confluence Token",
+            "✅ Set" if settings.internal_confluence_token else "❌ Missing",
+        )
+        table.add_row(
+            "External Confluence Token",
+            "✅ Set" if settings.external_confluence_token else "❌ Missing",
+        )
+        table.add_row(
+            "VDS Credentials",
+            "✅ Set" if settings.vds_username and settings.vds_password else "❌ Missing",
+        )
+
+        console.print(table)
+    else:
+        console.print(f"[red]❌ Unknown action: {action}[/red]")
+        console.print("[yellow]Available actions: load, status[/yellow]")
+        raise typer.Exit(1) from None
+
+
+def _run_service(service: str, args: list[str]) -> None:
+    if not args:
+        typer.echo(
+            f"Error: No arguments passed to '{service}'. "
+            "Append the underlying CLI command and flags.",
+            err=True,
+        )
+        raise typer.Exit(1) from None
+
+    load_environment()  # Ensure environment is loaded
+    exit_code = run_orchestrator(service, args, SCRIPT_DIR)
+    if exit_code != 0:
+        raise typer.Exit(exit_code) from None
+
+
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def git(ctx: typer.Context) -> None:
+    """Git repository operations."""
+    _run_service("git", list(ctx.args))
+
+
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def jira(ctx: typer.Context) -> None:
+    """JIRA operations."""
+    _run_service("jira", list(ctx.args))
+
+
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def confluence(ctx: typer.Context) -> None:
+    """Confluence operations."""
+    _run_service("confluence", list(ctx.args))
+
+
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def bitbucket(ctx: typer.Context) -> None:
+    """Bitbucket operations."""
+    _run_service("bitbucket", list(ctx.args))
+
+
+@app.command(context_settings=PASS_THRU_CONTEXT)
+def pdf(ctx: typer.Context) -> None:
+    """PDF orchestrator operations."""
+    _run_service("pdf", list(ctx.args))
+
+
+@app.command()
+def status() -> None:
+    """System status and health checks."""
+    settings = load_environment()
+    console.print("[cyan]📊 VDS Platform Status[/cyan]\n")
+
+    # Check orchestrators
+    table = Table(title="Orchestrator Status")
+    table.add_column("Orchestrator", style="cyan")
+    table.add_column("Status", style="magenta")
+
+    for name in ["jira", "confluence", "bitbucket", "git", "pdf"]:
+        path = SCRIPT_DIR / f"{name}_orchestrator"
+        status_text = "✅ Available" if path.exists() else "❌ Missing"
+        table.add_row(name.title(), status_text)
+
+    console.print(table)
+
+    # Check environment
+    env_table = Table(title="Environment Status")
+    env_table.add_column("Variable", style="cyan")
+    env_table.add_column("Status", style="magenta")
+
+    env_table.add_row(
+        "Bitbucket Token",
+        "✅ Set" if settings.bitbucket_access_token else "❌ Missing",
+    )
+    env_table.add_row(
+        "Internal Confluence Token",
+        "✅ Set" if settings.internal_confluence_token else "❌ Missing",
+    )
+    env_table.add_row(
+        "External Confluence Token",
+        "✅ Set" if settings.external_confluence_token else "❌ Missing",
+    )
+    env_table.add_row(
+        "VDS Credentials",
+        "✅ Set" if settings.vds_username and settings.vds_password else "❌ Missing",
+    )
+
+    console.print("\n")
+    console.print(env_table)
+
+
+@app.command()
+def version() -> None:
+    """Show version information."""
+    from . import __version__
+
+    console.print(f"[cyan]VDS Platform CLI v{__version__}[/cyan]")
+
+
+def main() -> None:
+    """Main entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()