@ngocsangairvds/vsaf 4.0.5 → 4.0.7

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

@@ -0,0 +1,111 @@
+"""Environment management using pydantic-settings.
+
+Based on pydantic-settings v2.12.0+ API.
+Loads VDS settings through the shared cross-platform path/config layer.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from vds_cli_common.env import load_shared_env
+
+
+class VDSSettings(BaseSettings):
+    """VDS environment settings loaded through the shared VDS env file."""
+
+    model_config = SettingsConfigDict(
+        env_file=None,
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    vds_username: str | None = None
+    vds_password: str | None = None
+    bitbucket_access_token: str | None = None
+    bitbucket_token: str | None = None
+    internal_confluence_token: str | None = None
+    external_confluence_token: str | None = None
+    # Git orchestrator settings (loaded from the shared VDS env file)
+    vds_git_auto_regenerate_manifest: str | None = None
+    vds_git_concurrency_default: str | None = None
+    # Bitbucket URL configuration (FR-21.1.1)
+    # Primary: VDS_BITBUCKET_URL (recommended)
+    # Legacy aliases: VDS_BITBUCKET_HTTP_BASE, BITBUCKET_BASE_URL
+    vds_bitbucket_url: str | None = None  # Primary env var
+    vds_bitbucket_http_base: str | None = None  # Legacy alias
+    bitbucket_base_url: str | None = None  # Legacy alias
+    # Git network settings (timeouts, buffers, retries)
+    vds_git_http_timeout: str | None = None  # seconds (default: 300)
+    vds_git_http_post_buffer: str | None = None  # bytes (default: 524288000 = 500MB)
+    vds_git_http_low_speed_limit: str | None = None  # bytes/sec (default: 1000 = 1KB/s)
+    vds_git_http_low_speed_time: str | None = None  # seconds (default: 300)
+    vds_git_retries: str | None = None  # number of retries (default: 2)
+    vds_git_backoff: str | None = None  # backoff multiplier (default: 1.5)
+    # Git projects configuration (comma-separated list, e.g., "lep,insurance,saving,ekyc")
+    vds_git_projects: str | None = None
+
+
+def parse_git_projects(projects_str: str | None) -> set[str]:
+    """Parse comma-separated project list from environment variable.
+
+    Args:
+        projects_str: Comma-separated list of project IDs (e.g., "lep,insurance,saving,ekyc")
+
+    Returns:
+        Set of project IDs with whitespace trimmed
+
+    Example:
+        >>> parse_git_projects("lep,insurance,saving,ekyc")
+        {'lep', 'insurance', 'saving', 'ekyc'}
+        >>> parse_git_projects("lep, insurance , saving")
+        {'lep', 'insurance', 'saving'}
+    """
+    if not projects_str:
+        return set()
+    return {project.strip() for project in projects_str.split(",") if project.strip()}
+
+
+def get_bitbucket_url(settings: VDSSettings | None = None) -> str:
+    """Get Bitbucket URL with proper priority resolution (FR-21.1.1).
+
+    Priority order:
+    1. VDS_BITBUCKET_URL (primary - recommended)
+    2. VDS_BITBUCKET_HTTP_BASE (legacy alias)
+    3. BITBUCKET_BASE_URL (legacy alias)
+    4. Default: http://bitbucket.digital.vn/
+
+    Args:
+        settings: Optional VDSSettings instance. If None, loads from environment.
+
+    Returns:
+        Resolved Bitbucket URL (without trailing slash)
+
+    Example:
+        >>> url = get_bitbucket_url()
+        >>> print(url)
+        'http://bitbucket.digital.vn'
+    """
+    if settings is None:
+        settings = load_environment()
+
+    url = (
+        settings.vds_bitbucket_url
+        or settings.vds_bitbucket_http_base
+        or settings.bitbucket_base_url
+        or "http://bitbucket.digital.vn/"
+    )
+    return url.rstrip("/")
+
+
+def load_environment() -> VDSSettings:
+    """Load environment variables from the shared VDS env file.
+
+    Returns:
+        VDSSettings: Loaded settings instance
+
+    Example:
+        >>> settings = load_environment()
+        >>> if settings.vds_username:
+        ...     print("Credentials loaded")
+    """
+    load_shared_env()
+    return VDSSettings()

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

@@ -0,0 +1,281 @@
+"""Lifecycle commands for the canonical git credential helper.
+
+Spec: who-ecosystem-alignment Phase 5 v0.7.0 — FR-23 (vds-cli env lifecycle),
+FR-24 (single canonical artifact), AC-23.7 (file modes), AC-23.8 (subprocess
+shell=False), AC-24.4/AC-24.5/AC-24.6 (legacy artifact cleanup + signature
+check + state migration).
+
+Per FR-25 AC-25.3, this module runs in the vds-scripts venv and freely
+reuses third-party + vds-scripts packages. The helper itself
+(assets/git-credential-helper.py) has the no-venv constraint, NOT this
+module.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import subprocess
+from importlib import resources
+from pathlib import Path
+from typing import NamedTuple
+
+INSTALLED_BINARY_NAME = "git-credential-vds"
+HELPER_SUBDIR = "bin"
+VDS_DIR = ".vds"
+COOLDOWN_FILE = ".git-credential-helper-cooldown.json"
+LEGACY_STATE_FILE = ".git_helper_state.json"
+LEGACY_HELPER_FILENAMES = (
+    "git_credential_helper.py",
+    "git_credential_helper.py.bak",
+)
+LEGACY_TMP_HELPER = Path("/tmp/git_credential_helper_v2.py")
+
+INSTALLED_MODE = 0o700
+DIR_MODE = 0o700
+STATE_MODE = 0o600
+
+SIGNATURE_MARKERS = ("VDS_USERNAME", "def cmd_get")
+
+
+class InstallResult(NamedTuple):
+    target: Path
+    removed: list[Path]
+    preserved: list[Path]
+    migrated_state: Path | None
+    probe_ok: bool
+
+
+class VerifyCheck(NamedTuple):
+    name: str
+    detail: str
+    ok: bool
+
+
+def _home() -> Path:
+    return Path.home()
+
+
+def _installed_path() -> Path:
+    return _home() / VDS_DIR / HELPER_SUBDIR / INSTALLED_BINARY_NAME
+
+
+def _state_path() -> Path:
+    return _home() / VDS_DIR / COOLDOWN_FILE
+
+
+def _legacy_state_path() -> Path:
+    return _home() / VDS_DIR / LEGACY_STATE_FILE
+
+
+def _read_asset() -> str:
+    """Read the bundled canonical helper source per AC-23.2(a)."""
+    return resources.files("vds_cli").joinpath("assets/git-credential-helper.py").read_text(encoding="utf-8")
+
+
+def _signature_match(content: str) -> bool:
+    """AC-24.6: content matches pre-FR-24 helper signature."""
+    return all(marker in content for marker in SIGNATURE_MARKERS)
+
+
+def _cleanup_legacy_artifacts(*, force: bool = False) -> tuple[list[Path], list[Path]]:
+    """Remove pre-FR-24 file artifacts. Returns (removed, preserved)."""
+    removed: list[Path] = []
+    preserved: list[Path] = []
+    candidates: list[Path] = [_home() / VDS_DIR / name for name in LEGACY_HELPER_FILENAMES]
+    candidates.append(LEGACY_TMP_HELPER)
+    for path in candidates:
+        if not path.exists():
+            continue
+        if not force:
+            try:
+                content = path.read_text(encoding="utf-8")
+            except OSError:
+                preserved.append(path)
+                continue
+            if not _signature_match(content):
+                preserved.append(path)
+                continue
+        try:
+            path.unlink()
+            removed.append(path)
+        except OSError:
+            preserved.append(path)
+    return removed, preserved
+
+
+def _migrate_legacy_state() -> Path | None:
+    """AC-24.5: migrate legacy state file if present and new path is free."""
+    legacy = _legacy_state_path()
+    new = _state_path()
+    if not legacy.exists():
+        return None
+    if new.exists():
+        with contextlib.suppress(OSError):
+            legacy.unlink()
+        return None
+    try:
+        os.rename(str(legacy), str(new))
+        os.chmod(new, STATE_MODE)
+        return new
+    except OSError:
+        return None
+
+
+def _self_probe() -> bool:
+    """AC-23.2(d): stdin-sim allowlist-miss should yield no output, exit 0."""
+    target = _installed_path()
+    if not target.exists():
+        return False
+    try:
+        result = subprocess.run(
+            [str(target.resolve()), "get"],
+            input="protocol=https\nhost=allowlist-miss-probe.example\n\n",
+            capture_output=True,
+            text=True,
+            timeout=5,
+            check=False,
+            shell=False,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0 and result.stdout == ""
+
+
+def install(*, force: bool = False) -> InstallResult:
+    """Install canonical git credential helper.
+
+    AC-23.2(a-e) + AC-23.7 + AC-23.8 + AC-24.4 + AC-24.5 + AC-24.6.
+    """
+    target = _installed_path()
+    target.parent.mkdir(mode=DIR_MODE, parents=True, exist_ok=True)
+    os.chmod(target.parent, DIR_MODE)
+
+    asset_content = _read_asset()
+    target.write_text(asset_content, encoding="utf-8")
+    os.chmod(target, INSTALLED_MODE)
+
+    abs_path = str(target.resolve())
+    subprocess.run(
+        ["git", "config", "--global", "credential.helper", abs_path],
+        check=True,
+        shell=False,
+    )
+
+    removed, preserved = _cleanup_legacy_artifacts(force=force)
+    migrated = _migrate_legacy_state()
+    probe_ok = _self_probe()
+
+    return InstallResult(
+        target=target,
+        removed=removed,
+        preserved=preserved,
+        migrated_state=migrated,
+        probe_ok=probe_ok,
+    )
+
+
+def verify(*, reset_cooldown: bool = False) -> tuple[int, list[VerifyCheck]]:
+    """Verify install state. Returns (exit_code, checks). exit 0 iff all pass."""
+    checks: list[VerifyCheck] = []
+    target = _installed_path()
+
+    file_ok = target.exists()
+    checks.append(VerifyCheck("Helper file", str(target), file_ok))
+
+    exec_ok = file_ok and (target.stat().st_mode & 0o111) != 0
+    checks.append(
+        VerifyCheck(
+            "Executable",
+            "mode +x" if exec_ok else "missing +x bits",
+            exec_ok,
+        )
+    )
+
+    abs_path = str(target.resolve()) if file_ok else ""
+    try:
+        result = subprocess.run(
+            ["git", "config", "--global", "--get", "credential.helper"],
+            capture_output=True,
+            text=True,
+            check=False,
+            shell=False,
+        )
+        configured = result.stdout.strip() if result.returncode == 0 else ""
+    except OSError:
+        configured = ""
+    config_ok = bool(configured) and (configured == abs_path or configured.endswith(INSTALLED_BINARY_NAME))
+    checks.append(VerifyCheck("Git config", configured or "<unset>", config_ok))
+
+    if reset_cooldown:
+        state = _state_path()
+        try:
+            state.parent.mkdir(parents=True, exist_ok=True)
+            state.write_text(
+                json.dumps({"failures": [], "cooldown_until": 0}),
+                encoding="utf-8",
+            )
+            os.chmod(state, STATE_MODE)
+            checks.append(VerifyCheck("Cooldown reset", "state cleared", True))
+        except OSError as exc:
+            checks.append(VerifyCheck("Cooldown reset", f"failed: {exc}", False))
+
+    exit_code = 0 if all(check.ok for check in checks) else 1
+    return exit_code, checks
+
+
+def remove(*, purge: bool = False) -> dict:
+    """Uninstall helper. Idempotent — safe when nothing is installed (AC-23.4)."""
+    target = _installed_path()
+    deleted_binary = False
+    if target.exists():
+        try:
+            target.unlink()
+            deleted_binary = True
+        except OSError:
+            pass
+
+    with contextlib.suppress(OSError):
+        subprocess.run(
+            ["git", "config", "--global", "--unset", "credential.helper"],
+            capture_output=True,
+            check=False,
+            shell=False,
+        )
+
+    deleted_state = False
+    if purge:
+        state = _state_path()
+        if state.exists():
+            try:
+                state.unlink()
+                deleted_state = True
+            except OSError:
+                pass
+
+    return {"deleted_binary": deleted_binary, "deleted_state": deleted_state}
+
+
+def status() -> tuple[str, str]:
+    """For doctor command. Returns (status_word, remediation_hint)."""
+    target = _installed_path()
+    if not target.exists():
+        return "missing", "run `vds-cli env install-git-helper`"
+    if (target.stat().st_mode & 0o111) == 0:
+        return "broken", "run `vds-cli env install-git-helper` to repair file mode"
+    return "installed", ""
+
+
+__all__ = [
+    "DIR_MODE",
+    "INSTALLED_BINARY_NAME",
+    "INSTALLED_MODE",
+    "STATE_MODE",
+    "InstallResult",
+    "VerifyCheck",
+    "install",
+    "remove",
+    "status",
+    "verify",
+]

package/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/google_sheets_orchestrator/__init__.py

@@ -0,0 +1,3 @@
+from .google_sheets_orchestrator import app as app
+
+__all__ = ["app"]

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

@@ -0,0 +1,173 @@
+from pathlib import Path
+
+import gspread
+import structlog
+import typer
+from rich.console import Console
+from vds_cli_common.paths import get_vds_config_root
+
+console = Console()
+app = typer.Typer(help="Google Sheets orchestrator operations.")
+logger = structlog.get_logger(__name__)
+
+GOOGLE_SHEETS_SCOPE = [
+    "https://spreadsheets.google.com/feeds",
+    "https://www.googleapis.com/auth/drive",
+]
+
+
+def _build_client(auth_method: str, credentials_path: Path | None):
+    method = auth_method.strip().lower()
+    if method == "service_account":
+        resolved_path = credentials_path or (get_vds_config_root() / "google_credentials.json")
+        if not resolved_path.exists():
+            console.print(f"[bold red]Error:[/bold red] Service account credentials file not found at {resolved_path}")
+            raise typer.Exit(code=1) from None
+
+        creds = ServiceAccountCredentials.from_json_keyfile_name(
+            str(resolved_path),
+            GOOGLE_SHEETS_SCOPE,
+        )
+        client = gspread.service_account(credentials=creds)
+        console.print(f"[bold green]Authenticated using service account: [/bold green]{resolved_path}")
+        return client
+
+    if method == "oauth":
+        resolved_path = credentials_path or (get_vds_config_root() / "gspread_oauth.json")
+        resolved_path.parent.mkdir(parents=True, exist_ok=True)
+        client = gspread.oauth(
+            scopes=GOOGLE_SHEETS_SCOPE,
+            credentials_filename=resolved_path,
+            authorized_user_filename=resolved_path.with_name("authorized_user.json"),
+        )
+        console.print(f"[bold green]Authenticated using OAuth: [/bold green]{resolved_path}")
+        return client
+
+    if method == "none":
+        # gspread still needs a client object even when opening public sheets.
+        console.print("[bold green]Attempting to read as a public sheet.[/bold green]")
+        return gspread.service_account()
+
+    console.print(
+        "[bold red]Error:[/bold red] Invalid authentication method: "
+        f"{auth_method}. Choose 'service_account', 'oauth', or 'none'."
+    )
+    raise typer.Exit(code=1) from None
+
+
+@app.command()
+def read(
+    spreadsheet_url: str = typer.Option(
+        ...,
+        "--spreadsheet-url",
+        "-u",
+        help="URL of the Google Spreadsheet.",
+    ),
+    sheet_name: str = typer.Option(
+        "Sheet1",
+        "--sheet-name",
+        "-n",
+        help="Name of the worksheet to read.",
+    ),
+    auth_method: str = typer.Option(
+        "service_account",
+        "--auth-method",
+        "-a",
+        help="Authentication method: 'service_account', 'oauth', or 'none' (for public sheets).",
+    ),
+    credentials_path: Path | None = typer.Option(
+        None,
+        "--credentials-path",
+        "-c",
+        help="Path to the Google credentials file (e.g., service_account.json).",
+    ),
+):
+    """Read data from a specified Google Sheet and print it to the console."""
+    client = _build_client(auth_method, credentials_path)
+    try:
+        spreadsheet = client.open_by_url(spreadsheet_url)
+        worksheet = spreadsheet.worksheet(sheet_name)
+        data = worksheet.get_all_values()
+
+        if data:
+            console.print(
+                f"[bold green]Successfully read data from '{sheet_name}' in '{spreadsheet.title}':[/bold green]"
+            )
+            for row_idx, row in enumerate(data, start=1):
+                logger.info(f"Row {row_idx}", row=row)
+        else:
+            console.print(f"[bold yellow]No data found in sheet '{sheet_name}' in '{spreadsheet.title}'.[/bold yellow]")
+
+    except gspread.exceptions.SpreadsheetNotFound:
+        console.print(f"[bold red]Error:[/bold red] Spreadsheet not found at URL: {spreadsheet_url}")
+        logger.exception("Spreadsheet not found", url=spreadsheet_url)
+        raise typer.Exit(code=1) from None
+    except gspread.exceptions.WorksheetNotFound:
+        console.print(f"[bold red]Error:[/bold red] Worksheet '{sheet_name}' not found in the spreadsheet.")
+        logger.exception("Worksheet not found", sheet_name=sheet_name, url=spreadsheet_url)
+        console.print("[bold yellow]Available worksheets:[/bold yellow]")
+        try:
+            spreadsheet = client.open_by_url(spreadsheet_url)
+            for worksheet in spreadsheet.worksheets():
+                console.print(f"- {worksheet.title}")
+        except Exception as exc:
+            logger.exception("Failed to list worksheets")
+            console.print(f"[bold red]Could not list worksheets: {exc}[/bold red]")
+        raise typer.Exit(code=1) from None
+    except gspread.exceptions.APIError as exc:
+        console.print(f"[bold red]Error:[/bold red] Google Sheets API error: {exc}")
+        logger.exception("Google Sheets API error", error=str(exc), auth_method=auth_method)
+        console.print("[bold yellow]Please check your credentials and spreadsheet permissions.[/bold yellow]")
+        if "Request had insufficient authentication scopes." in str(exc) and auth_method == "service_account":
+            console.print(
+                "[bold yellow]Ensure your service account has editor access to the spreadsheet "
+                "and Google Drive API is enabled.[/bold yellow]"
+            )
+        if "Requested entity was not found" in str(exc) and auth_method == "none":
+            console.print(
+                "[bold yellow]The spreadsheet might not be publicly accessible. Try "
+                "'oauth' or 'service_account' authentication.[/bold yellow]"
+            )
+        raise typer.Exit(code=1) from None
+    except Exception as exc:
+        logger.exception("An unexpected error occurred")
+        console.print(f"[bold red]An unexpected error occurred:[/bold red] {exc}")
+        raise typer.Exit(code=1) from None
+
+
+@app.command(name="list-worksheets")
+def list_worksheets(
+    spreadsheet_url: str = typer.Option(
+        ...,
+        "--spreadsheet-url",
+        "-u",
+        help="URL of the Google Spreadsheet.",
+    ),
+    auth_method: str = typer.Option(
+        "service_account",
+        "--auth-method",
+        "-a",
+        help="Authentication method: 'service_account', 'oauth', or 'none' (for public sheets).",
+    ),
+    credentials_path: Path | None = typer.Option(
+        None,
+        "--credentials-path",
+        "-c",
+        help="Path to the Google credentials file (e.g., service_account.json).",
+    ),
+):
+    """List all worksheets in a specified Google Spreadsheet."""
+    client = _build_client(auth_method, credentials_path)
+    try:
+        spreadsheet = client.open_by_url(spreadsheet_url)
+        console.print(f"[bold green]Worksheets in '{spreadsheet.title}':[/bold green]")
+        for worksheet in spreadsheet.worksheets():
+            console.print(f"- {worksheet.title}")
+    except Exception as exc:
+        logger.exception("Failed to list worksheets")
+        console.print(f"[bold red]An error occurred while listing worksheets:[/bold red] {exc}")
+        raise typer.Exit(code=1) from None
+
+
+if __name__ == "__main__":
+    app()