@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_cli/README.md

@@ -0,0 +1,201 @@
+# VDS CLI - Cross-Platform Python CLI
+
+Cross-platform Python CLI wrapper for VDS Platform operations.
+
+## Installation (uv-native)
+
+```bash
+cd WHO-project/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
+./scripts/worktree_uv.sh 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 the shared VDS env file)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env load
+
+# Check environment status
+./scripts/worktree_uv.sh run --project vds_cli vds-cli env status
+
+# Check system status (orchestrators + environment)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli status
+
+# Run actionable diagnostics (router + env files + auth readiness)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli doctor
+```
+
+### Using Orchestrators
+
+```bash
+# JIRA operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" --limit 20
+./scripts/worktree_uv.sh run --project vds_cli vds-cli jira issue NTTC-123
+
+# Confluence operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence search --cql 'space="TDOV" and type=page' --limit 20
+./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence content page 99647801 --expand body.view,version,space
+./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence -- --json-only crawl-tree "http://confluence.digital.vn/pages/viewpage.action?pageId=88716667" --out /tmp/confluence_evidence --depth 1 --emit-corpus --emit-link-graph
+
+# Bitbucket operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket projects
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repositories INSURANCE
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repo get INSURANCE vds-ai-memory
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repo create INSURANCE new-repo --yes
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repo update INSURANCE vds-ai-memory --description "Updated description" --yes
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket repo delete INSURANCE old-repo --yes
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket commit-status get INSURANCE vds-ai-memory COMMIT_HASH --limit 20
+./scripts/worktree_uv.sh run --project vds_cli vds-cli bitbucket branch-permissions list INSURANCE --repo vds-ai-memory --json-only
+
+# SonarQube operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube ping
+./scripts/worktree_uv.sh run --project vds_cli vds-cli sonarqube qualitygate --project ekyc-business
+
+# Git operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli git clone lep
+./scripts/worktree_uv.sh run --project vds_cli vds-cli git pull --project insurance
+./scripts/worktree_uv.sh run --project vds_cli vds-cli git status --match "*service*"
+
+# Elasticsearch operations (via Kibana Console Proxy)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic ping
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic user-info
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic search --index "logs-*" --size 10
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic count --index "logs-*"
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic search --qs "level:ERROR AND timeout"
+
+# Grafana logs operations
+./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana health
+./scripts/worktree_uv.sh run --project vds_cli vds-cli grafana search --index "gw-*" --limit 20
+
+# Diagram generation (C4, sequence, component, use case, mermaid)
+./scripts/worktree_uv.sh run --project vds_cli vds-cli diagrams --project INSURANCE --list
+./scripts/worktree_uv.sh run --project vds_cli vds-cli diagrams --project INSURANCE --service insurance-policy-business
+./scripts/worktree_uv.sh run --project vds_cli vds-cli diagrams --project INSURANCE --c4 --mermaid --use-case
+./scripts/worktree_uv.sh run --project vds_cli vds-cli diagrams --project INSURANCE --hierarchy --export-dsl
+
+# BRD coverage validation
+./scripts/worktree_uv.sh run --project vds_cli vds-cli brd -- validate
+./scripts/worktree_uv.sh run --project vds_cli vds-cli brd -- validate --root WHO-project/insurance-document --report /tmp/brd_coverage_report.json
+
+# Excel target-state status workbook
+./scripts/worktree_uv.sh run --project vds_cli vds-cli excel -- target-state-status
+
+# Task breakdown management
+./scripts/worktree_uv.sh run --project vds_cli vds-cli tasks -- audit
+./scripts/worktree_uv.sh run --project vds_cli vds-cli tasks -- refine
+./scripts/worktree_uv.sh run --project vds_cli vds-cli tasks -- normalize
+./scripts/worktree_uv.sh run --project vds_cli vds-cli tasks -- sync
+```
+
+### Help
+
+```bash
+# Show main help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli --help
+
+# Show command help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli jira --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli confluence --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli elastic --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli diagrams --help
+```
+
+**`vds-cli` is the ONLY valid user-facing entry point.** Direct executables listed in `[project.scripts]` exist only for router binding and must not be invoked by operators. Use `vds-cli <service> --help` for discovery.
+
+## Features
+
+- ✅ **Cross-platform**: Works on Mac, Linux, and Windows
+- ✅ **Environment Management**: Automatic loading from the shared VDS env file via `vds_cli_common` (populates `os.environ`)
+- ✅ **Unified Interface**: Single CLI for all orchestrators (JIRA, Confluence, Bitbucket, Git, SonarQube, Elastic, Diagrams, Excel, Tasks, PDF)
+- ✅ **Strict Router Validation**: `vds-cli` verifies routed entrypoints exist in `[project.scripts]` and their target modules are present under `src/`
+- ✅ **Doctor Diagnostics**: `vds-cli doctor` reports concrete recommended actions for missing env/auth and broken routed services
+- ✅ **Rich Console Output**: Beautiful tables and formatted output
+- ✅ **Type-Safe Configuration**: Full Python type hints and validation
+- ✅ **Quality Assured**: 77% test coverage, zero ruff linting issues
+
+## Configuration Precedence
+
+`vds-cli` follows a deterministic precedence model:
+
+1. Existing shell environment variables (`os.environ`)
+2. Shared VDS env file (effective config-root `.env`)
+3. `WHO-project/vds-scripts/.env` (optional fallback)
+
+`vds-cli env load` and routed commands load values into the current CLI process.  
+They do not export values back into your interactive shell session.
+
+## Migration from Bash CLI
+
+The Python CLI (`vds-cli`) replaces the legacy bash wrapper (now removed). The command interface is identical:
+
+**Before (bash)**:
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli jira search "project = NTTC" 20
+```
+
+**After (Python)**:
+
+```bash
+./scripts/worktree_uv.sh 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 WHO-project/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)
+- Shared VDS env file 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
+tings management
+nagement
+tings management
+ntials
+
+## 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
+tings management
+nagement
+tings management

package/skills/vds-skill/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/skills/vds-skill/vds-scripts/vds_cli/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "vds-cli"
+version = "4.0.0"
+description = "Cross-platform VDS Platform CLI"
+requires-python = ">=3.14"
+dependencies = [
+    "typer>=0.24.1",
+    "rich>=14.3.3",               # Latest: 14.3.3 (Feb 2026)
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",  # Latest: 2.12.0 (Nov 2025) - Context7: /pydantic/pydantic-settings
+    "vds-bitbucket-orchestrator", # For regenerate-manifest command
+    "vds-google-sheets-orchestrator",
+    "vds-cli-common",             # Shared CLI infrastructure
+    "sqlalchemy>=2.0",            # ecosystem report dashboard (TSK-P3-3.x)
+    "pyyaml>=6.0",                # confluence_sync manifest parsing
+    "httpx>=0.28",                # doctor: Ollama reachability probe
+]
+
+[project.scripts]
+vds-cli = "vds_cli.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.20.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vds_cli"]
+include = ["src/vds_cli/assets/**/*"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vds_cli", "pyproject.toml", "README.md"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.14.11",
+]
+
+[tool.uv.sources]
+vds-bitbucket-orchestrator = { workspace = true }
+vds-google-sheets-orchestrator = { workspace = true }
+vds-cli-common = { workspace = true }
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=5.0.0",
+    "ruff>=0.14.11",
+]

package/skills/vds-skill/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/skills/vds-skill/vds-scripts/vds_cli/src/vds_cli/assets/git-credential-helper.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Git credential helper for VDS workflows.
+
+Canonical install path: $HOME/.vds/bin/git-credential-vds
+Canonical source: WHO-project/vds-scripts/vds_cli/src/vds_cli/assets/git-credential-helper.py
+
+Spec: who-ecosystem-alignment Phase 5 — FR-20 (host-filtered emission),
+      FR-21 (lockout-prevention with cooldown state file), FR-25 (logic
+      non-overlap policy).
+
+Per FR-25 AC-25.1, this helper MUST NOT import from any path requiring the
+vds-scripts venv to be active. Git invokes it in a bare shell context with
+no venv activation; even stdlib-only modules inside venv-installed packages
+are unreachable. Stdlib-only imports are enforced by a unit test in
+vds_cli/tests/test_git_credential_helper.py.
+
+Per FR-25 AC-25.2, the dotenv parsing logic below is a deliberate duplicate
+of vds_cli_common.env._parse_env_file (see
+vds_cli_common/src/vds_cli_common/env.py:23-42). The token-vs-basic
+preference logic is a deliberate duplicate of
+BitbucketSettings.get_auth_kwargs (see
+bitbucket_orchestrator/src/vds_bitbucket_orchestrator/config.py:106).
+
+Both duplications are required by the no-venv constraint and are kept in
+sync per AC-25.4: PRs touching either source-of-truth MUST audit and update
+this file in the same change.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# AC-21.5: thresholds are module-level constants, NOT env-configurable, to keep
+# the operator surface narrow. Power users may edit these directly if absolutely
+# required, but the default 3 / 60s / 300s is tuned for Bitbucket DC.
+FAILURE_THRESHOLD = 3
+FAILURE_WINDOW_SEC = 60
+COOLDOWN_SEC = 300
+
+# AC-21.7: state file mode. Mandatory.
+STATE_FILE_MODE = 0o600
+
+# Default host allowlist per FR-20 AC-20.1. Extensible via VDS_BITBUCKET_HOSTS
+# in ~/.vds/.env (NEVER from shell env, per AC-20.6).
+ALLOWLIST_DEFAULT = frozenset({"bitbucket.digital.vn"})
+
+
+def _home() -> Path:
+    """Resolve HOME — git invokes the helper with HOME set in the environment."""
+    return Path(os.environ.get("HOME", str(Path.home())))
+
+
+def _env_file() -> Path:
+    return _home() / ".vds" / ".env"
+
+
+def _state_file() -> Path:
+    return _home() / ".vds" / ".git-credential-helper-cooldown.json"
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    """Stdlib-only dotenv parser. Mirrors vds_cli_common.env._parse_env_file."""
+    values: dict[str, str] = {}
+    if not path.exists():
+        return values
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return values
+    for raw_line in text.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[7:].lstrip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip()
+        if value and value[0] == value[-1] and value[0] in {"'", '"'}:
+            value = value[1:-1]
+        if key:
+            values[key] = value
+    return values
+
+
+def _is_configured(value: str | None) -> bool:
+    """AC-19.5: configured iff non-empty after whitespace strip."""
+    return bool(value and value.strip())
+
+
+def _read_stdin_kv() -> dict[str, str]:
+    """Read git's key=value stdin protocol."""
+    info: dict[str, str] = {}
+    try:
+        data = sys.stdin.read()
+    except Exception:
+        return info
+    for line in data.splitlines():
+        if "=" in line:
+            k, _, v = line.partition("=")
+            info[k.strip()] = v.strip()
+    return info
+
+
+def _allowlist(env: dict[str, str]) -> frozenset[str]:
+    """AC-20.6: read VDS_BITBUCKET_HOSTS ONLY from env file dict, never shell env."""
+    extra = env.get("VDS_BITBUCKET_HOSTS", "").strip()
+    hosts = set(ALLOWLIST_DEFAULT)
+    if extra:
+        hosts.update(h.strip() for h in extra.split(",") if h.strip())
+    return frozenset(hosts)
+
+
+def _load_state() -> dict:
+    """AC-21.4: state file is human-inspectable JSON. Returns empty if missing/malformed."""
+    path = _state_file()
+    if not path.exists():
+        return {"failures": [], "cooldown_until": 0}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {"failures": [], "cooldown_until": 0}
+
+
+def _save_state(state: dict) -> None:
+    """AC-21.7: write state file with mode 0600. Best-effort (AC-21 silent on failure)."""
+    path = _state_file()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(state), encoding="utf-8")
+        os.chmod(path, STATE_FILE_MODE)
+    except OSError:
+        pass
+
+
+def _in_cooldown(state: dict, now: float) -> bool:
+    return float(state.get("cooldown_until", 0)) > now
+
+
+def _record_failure(state: dict, now: float) -> dict:
+    """Append failure timestamp; trip cooldown if threshold met within window."""
+    failures = [float(t) for t in state.get("failures", []) if now - float(t) <= FAILURE_WINDOW_SEC]
+    failures.append(now)
+    if len(failures) >= FAILURE_THRESHOLD:
+        return {"failures": [], "cooldown_until": now + COOLDOWN_SEC}
+    return {"failures": failures, "cooldown_until": float(state.get("cooldown_until", 0))}
+
+
+def _reset_state() -> dict:
+    return {"failures": [], "cooldown_until": 0}
+
+
+def _emit(username: str, password: str) -> None:
+    """AC-20.5: ONLY username= and password= to stdout. No stderr, no logs."""
+    sys.stdout.write(f"username={username}\n")
+    sys.stdout.write(f"password={password}\n")
+
+
+def cmd_get() -> int:
+    git_info = _read_stdin_kv()
+    host = git_info.get("host", "")
+
+    file_env = _parse_env_file(_env_file())
+    allowed = _allowlist(file_env)
+
+    # FR-20 AC-20.1+AC-20.2: silent fall-through for non-allowlisted hosts.
+    if host not in allowed:
+        return 0
+
+    state = _load_state()
+    now = time.time()
+    if _in_cooldown(state, now):
+        # AC-21.6: stderr notice with INTEGER countdown only — no credential content.
+        # This is the sole permitted stderr emission per AC-20.5 carve-out.
+        remaining = int(float(state["cooldown_until"]) - now)
+        sys.stderr.write(f"in cooldown until {remaining}s — falling through to other helpers\n")
+        return 0
+
+    # AC-19.5 + AC-20.3 + AC-25.2: token preferred over basic when both configured
+    # (whitespace-stripped). Mirrors BitbucketSettings.get_auth_kwargs.
+    username = file_env.get("VDS_USERNAME", "").strip()
+    token = file_env.get("BITBUCKET_TOKEN", "").strip()
+    password = file_env.get("VDS_PASSWORD", "").strip()
+
+    if _is_configured(username) and _is_configured(token):
+        _emit(username, token)
+        return 0
+    if _is_configured(username) and _is_configured(password):
+        _emit(username, password)
+        return 0
+    return 1  # no creds configured → let git prompt user
+
+
+def cmd_erase() -> int:
+    """Git rejected creds. Record failure for cooldown tracking (FR-21)."""
+    git_info = _read_stdin_kv()
+    host = git_info.get("host", "")
+    file_env = _parse_env_file(_env_file())
+    if host in _allowlist(file_env):
+        state = _record_failure(_load_state(), time.time())
+        _save_state(state)
+    return 0
+
+
+def cmd_store() -> int:
+    """Git accepted creds. Reset cooldown state (AC-21.3)."""
+    git_info = _read_stdin_kv()
+    host = git_info.get("host", "")
+    file_env = _parse_env_file(_env_file())
+    if host in _allowlist(file_env):
+        _save_state(_reset_state())
+    return 0
+
+
+def main() -> int:
+    if len(sys.argv) < 2:
+        return 0
+    action = sys.argv[1]
+    if action == "get":
+        return cmd_get()
+    if action == "erase":
+        return cmd_erase()
+    if action == "store":
+        return cmd_store()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())