@ngocsangairvds/vsaf 4.0.5 → 4.0.7

package/skills/vds-skill/vds-scripts/git_orchestrator/tests/unit/test_branch_probe.py

@@ -0,0 +1,327 @@
+"""Tests for vds_git_orchestrator.branch_probe — Phase 4 FR-P2 (TSK-P2.1).
+
+Covers:
+- probe_branch_candidates: happy path, partial matches, none found, timeout,
+  error, empty URL, unsupported scheme
+- probe_branch_hints: HEAD symref parsing, branch discovery, sample limiting,
+  timeout, error
+- _build_ls_remote_command: auth injection (both set, neither set, partial)
+- get_branch_candidates: canonical vs legacy ordering via env var
+"""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from vds_bitbucket_orchestrator.parsers import BitbucketBranchInfo, parse_default_branch
+from vds_git_orchestrator.branch_probe import (
+    _LEGACY_GIT_ORCHESTRATOR_ORDER,
+    BRANCH_CANDIDATES,
+    BranchHintResult,
+    BranchProbeResult,
+    _build_ls_remote_command,
+    get_branch_candidates,
+    probe_branch_candidates,
+    probe_branch_hints,
+)
+
+# ---------------------------------------------------------------------------
+# Helpers to mock asyncio.create_subprocess_exec
+# ---------------------------------------------------------------------------
+
+
+def _make_mock_process(stdout: str = "", stderr: str = "", returncode: int = 0) -> AsyncMock:
+    """Create a mock async process with given output."""
+    proc = AsyncMock()
+    proc.communicate = AsyncMock(return_value=(stdout.encode(), stderr.encode()))
+    proc.returncode = returncode
+    proc.kill = AsyncMock()
+    return proc
+
+
+# ===================================================================
+# _build_ls_remote_command — auth injection tests
+# ===================================================================
+
+
+class TestBuildLsRemoteCommand:
+    """Auth injection in _build_ls_remote_command."""
+
+    def test_auth_both_set(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VDS_USERNAME", "user")
+        monkeypatch.setenv("VDS_PASSWORD", "pass")
+        cmd = _build_ls_remote_command(remote_url="https://bitbucket/repo.git")
+        assert "-c" in cmd
+        # Find the config value after -c
+        c_idx = cmd.index("-c")
+        assert cmd[c_idx + 1].startswith("http.extraHeader=Authorization: Basic ")
+
+    def test_auth_neither_set(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        cmd = _build_ls_remote_command(remote_url="https://bitbucket/repo.git")
+        assert "-c" not in cmd
+
+    def test_auth_partial_only_username(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VDS_USERNAME", "user")
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        cmd = _build_ls_remote_command(remote_url="https://bitbucket/repo.git")
+        # Partial credentials should NOT inject auth
+        assert "-c" not in cmd
+
+    def test_auth_partial_only_password(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.setenv("VDS_PASSWORD", "pass")
+        cmd = _build_ls_remote_command(remote_url="https://bitbucket/repo.git")
+        assert "-c" not in cmd
+
+    def test_branch_candidates_appended(self) -> None:
+        cmd = _build_ls_remote_command(
+            remote_url="https://bitbucket/repo.git",
+            branch_candidates=("main", "release"),
+        )
+        assert "refs/heads/main" in cmd
+        assert "refs/heads/release" in cmd
+
+    def test_symref_flag(self) -> None:
+        cmd = _build_ls_remote_command(
+            remote_url="https://bitbucket/repo.git",
+            include_symref=True,
+        )
+        assert "--symref" in cmd
+
+    def test_no_symref_by_default(self) -> None:
+        cmd = _build_ls_remote_command(remote_url="https://bitbucket/repo.git")
+        assert "--symref" not in cmd
+
+
+# ===================================================================
+# probe_branch_candidates tests
+# ===================================================================
+
+
+class TestProbeBranchCandidates:
+    """probe_branch_candidates() async probing."""
+
+    @pytest.mark.asyncio
+    async def test_happy_path_all_candidates(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        stdout = (
+            "abc123\trefs/heads/main\n"
+            "def456\trefs/heads/release\n"
+            "ghi789\trefs/heads/master\n"
+            "jkl012\trefs/heads/staging\n"
+        )
+        proc = _make_mock_process(stdout=stdout)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_candidates("https://bitbucket/repo.git")
+        assert result.deterministic is True
+        assert result.available_branches == ["main", "release", "master", "staging"]
+        assert result.error is None
+
+    @pytest.mark.asyncio
+    async def test_partial_matches(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        stdout = "abc123\trefs/heads/release\n"
+        proc = _make_mock_process(stdout=stdout)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_candidates("https://bitbucket/repo.git")
+        assert result.deterministic is True
+        assert result.available_branches == ["release"]
+
+    @pytest.mark.asyncio
+    async def test_none_found(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        proc = _make_mock_process(stdout="")
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_candidates("https://bitbucket/repo.git")
+        assert result.deterministic is True
+        assert result.available_branches == []
+
+    @pytest.mark.asyncio
+    async def test_timeout(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        proc = _make_mock_process()
+        # First call raises TimeoutError (caught by wait_for handler),
+        # second call succeeds (cleanup after process.kill()).
+        proc.communicate = AsyncMock(side_effect=[TimeoutError, (b"", b"")])
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_candidates("https://bitbucket/repo.git", timeout=1.0)
+        assert result.deterministic is False
+        assert result.error == "ls_remote_timeout"
+
+    @pytest.mark.asyncio
+    async def test_nonzero_exit(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        proc = _make_mock_process(stderr="fatal: repo not found", returncode=128)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_candidates("https://bitbucket/repo.git")
+        assert result.deterministic is False
+        assert "fatal: repo not found" in (result.error or "")
+
+    @pytest.mark.asyncio
+    async def test_empty_url(self) -> None:
+        result = await probe_branch_candidates("")
+        assert result.deterministic is False
+        assert result.error == "missing_remote_url"
+
+    @pytest.mark.asyncio
+    async def test_unsupported_scheme(self) -> None:
+        result = await probe_branch_candidates("ftp://example.com/repo.git")
+        assert result.deterministic is False
+        assert "unsupported_remote_scheme" in (result.error or "")
+
+
+# ===================================================================
+# probe_branch_hints tests
+# ===================================================================
+
+
+class TestProbeBranchHints:
+    """probe_branch_hints() async discovery."""
+
+    @pytest.mark.asyncio
+    async def test_symref_head_parsed(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        stdout = (
+            "ref: refs/heads/main\tHEAD\n"
+            "abc123\trefs/heads/main\n"
+            "def456\trefs/heads/develop\n"
+            "ghi789\trefs/heads/feature/foo\n"
+        )
+        proc = _make_mock_process(stdout=stdout)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_hints("https://bitbucket/repo.git")
+        assert result.deterministic is True
+        assert result.default_branch == "main"
+        assert "main" in result.discovered_branches
+        assert "develop" in result.discovered_branches
+        assert result.discovered_branch_count == 3
+
+    @pytest.mark.asyncio
+    async def test_sample_limit(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        branches = "\n".join(f"abc{i}\trefs/heads/branch-{i}" for i in range(20))
+        proc = _make_mock_process(stdout=branches)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_hints("https://bitbucket/repo.git", sample_limit=3)
+        assert len(result.discovered_branches) == 3
+        assert result.discovered_branch_count == 20
+
+    @pytest.mark.asyncio
+    async def test_timeout(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        proc = _make_mock_process()
+        proc.communicate = AsyncMock(side_effect=[TimeoutError, (b"", b"")])
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_hints("https://bitbucket/repo.git", timeout=1.0)
+        assert result.deterministic is False
+        assert result.error == "ls_remote_timeout"
+
+    @pytest.mark.asyncio
+    async def test_empty_url(self) -> None:
+        result = await probe_branch_hints("")
+        assert result.deterministic is False
+        assert result.error == "missing_remote_url"
+
+    @pytest.mark.asyncio
+    async def test_nonzero_exit(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        proc = _make_mock_process(stderr="permission denied", returncode=1)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_hints("https://bitbucket/repo.git")
+        assert result.deterministic is False
+        assert "permission denied" in (result.error or "")
+
+    @pytest.mark.asyncio
+    async def test_no_head_symref(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_USERNAME", raising=False)
+        monkeypatch.delenv("VDS_PASSWORD", raising=False)
+        stdout = "abc123\trefs/heads/main\ndef456\trefs/heads/develop\n"
+        proc = _make_mock_process(stdout=stdout)
+        with patch("vds_git_orchestrator.branch_probe.asyncio.create_subprocess_exec", return_value=proc):
+            result = await probe_branch_hints("https://bitbucket/repo.git")
+        assert result.default_branch is None
+        assert len(result.discovered_branches) == 2
+
+
+# ===================================================================
+# get_branch_candidates — canonical vs legacy ordering
+# ===================================================================
+
+
+class TestGetBranchCandidates:
+    """get_branch_candidates() env var routing."""
+
+    def test_canonical_order_by_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv("VDS_SYNC_BRANCH_ORDER", raising=False)
+        assert get_branch_candidates() == BRANCH_CANDIDATES
+
+    def test_legacy_order_when_set(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VDS_SYNC_BRANCH_ORDER", "legacy")
+        assert get_branch_candidates() == _LEGACY_GIT_ORCHESTRATOR_ORDER
+
+    def test_legacy_case_insensitive(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VDS_SYNC_BRANCH_ORDER", "LEGACY")
+        assert get_branch_candidates() == _LEGACY_GIT_ORCHESTRATOR_ORDER
+
+    def test_non_legacy_value_returns_canonical(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("VDS_SYNC_BRANCH_ORDER", "something_else")
+        assert get_branch_candidates() == BRANCH_CANDIDATES
+
+
+# ===================================================================
+# Branch order rollback — TSK-P2.5 cross-package contracts
+# ===================================================================
+
+
+class TestBranchOrderRollback:
+    """Verify VDS_SYNC_BRANCH_ORDER=legacy preserves pre-Phase-4 behavior per consumer."""
+
+    def test_legacy_order_audit(self) -> None:
+        """Audit's pre-Phase-4 order was already main-first (canonical).
+
+        The constant audit now imports (BRANCH_CANDIDATES) must equal the
+        canonical order so audit behavior is unchanged regardless of the
+        legacy env var.
+        """
+        assert BRANCH_CANDIDATES == ("main", "release", "master", "staging")
+
+    def test_legacy_order_sync(self) -> None:
+        """Sync's pre-Phase-4 sentinel was ``"release"`` (``_DEFAULT_BRANCH``).
+
+        Verify that ``parse_default_branch`` with ``missing_sentinel="release"``
+        reproduces the old sync behavior when the Bitbucket API returns no
+        default branch.
+        """
+        result = parse_default_branch({}, missing_sentinel="release")
+        assert result == BitbucketBranchInfo(display_id="release", ref=None, missing=True)
+
+
+# ===================================================================
+# Dataclass contracts
+# ===================================================================
+
+
+class TestDataclassContracts:
+    """Frozen dataclass immutability."""
+
+    def test_branch_probe_result_frozen(self) -> None:
+        result = BranchProbeResult(deterministic=True, available_branches=["main"])
+        with pytest.raises(AttributeError):
+            result.deterministic = False  # type: ignore[misc]
+
+    def test_branch_hint_result_frozen(self) -> None:
+        result = BranchHintResult(deterministic=True, default_branch="main")
+        with pytest.raises(AttributeError):
+            result.deterministic = False  # type: ignore[misc]

package/skills/vds-skill/vds-scripts/git_orchestrator/tests/unit/test_protocols.py

@@ -0,0 +1,132 @@
+"""Tests for vds_git_orchestrator.protocols — Phase 4 FR-P4 (TSK-P3.1).
+
+Covers:
+- SyncableRepo protocol structural matching via isinstance
+- Rejection of objects missing required properties
+- Package-level re-export equivalence
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vds_git_orchestrator.protocols import SyncableRepo
+
+
+class _CompleteSyncable:
+    """Minimal concrete class satisfying all 5 SyncableRepo properties."""
+
+    @property
+    def name(self) -> str:
+        return "test-repo"
+
+    @property
+    def project(self) -> str:
+        return "INSURANCE"
+
+    @property
+    def branch(self) -> str:
+        return "main"
+
+    @property
+    def url(self) -> str | None:
+        return "https://bitbucket.example.com/scm/ins/test-repo.git"
+
+    @property
+    def sync_metadata(self) -> dict[str, Any]:
+        return {"preserve_local_path": True}
+
+
+class _NoneUrlSyncable(_CompleteSyncable):
+    """Variant where url returns None (valid per protocol)."""
+
+    @property
+    def url(self) -> str | None:
+        return None
+
+
+class _MissingName:
+    """Object missing the 'name' property."""
+
+    @property
+    def project(self) -> str:
+        return "P"
+
+    @property
+    def branch(self) -> str:
+        return "main"
+
+    @property
+    def url(self) -> str | None:
+        return None
+
+    @property
+    def sync_metadata(self) -> dict[str, Any]:
+        return {}
+
+
+class _MissingSyncMetadata:
+    """Object missing the 'sync_metadata' property."""
+
+    @property
+    def name(self) -> str:
+        return "r"
+
+    @property
+    def project(self) -> str:
+        return "P"
+
+    @property
+    def branch(self) -> str:
+        return "main"
+
+    @property
+    def url(self) -> str | None:
+        return None
+
+
+class TestSyncableRepoProtocol:
+    """Verify SyncableRepo structural matching via isinstance."""
+
+    def test_complete_object_satisfies_protocol(self) -> None:
+        obj = _CompleteSyncable()
+        assert isinstance(obj, SyncableRepo)
+
+    def test_none_url_satisfies_protocol(self) -> None:
+        obj = _NoneUrlSyncable()
+        assert isinstance(obj, SyncableRepo)
+
+    def test_property_values_accessible(self) -> None:
+        obj = _CompleteSyncable()
+        assert obj.name == "test-repo"
+        assert obj.project == "INSURANCE"
+        assert obj.branch == "main"
+        assert obj.url == "https://bitbucket.example.com/scm/ins/test-repo.git"
+        assert obj.sync_metadata == {"preserve_local_path": True}
+
+    def test_missing_name_rejected(self) -> None:
+        obj = _MissingName()
+        assert not isinstance(obj, SyncableRepo)
+
+    def test_missing_sync_metadata_rejected(self) -> None:
+        obj = _MissingSyncMetadata()
+        assert not isinstance(obj, SyncableRepo)
+
+    def test_plain_dict_rejected(self) -> None:
+        obj = {"name": "r", "project": "P", "branch": "m", "url": None, "sync_metadata": {}}
+        assert not isinstance(obj, SyncableRepo)
+
+
+class TestPackageExport:
+    """Verify SyncableRepo is re-exported from the package root."""
+
+    def test_import_from_package_root(self) -> None:
+        from vds_git_orchestrator import SyncableRepo as PkgProto
+        from vds_git_orchestrator.protocols import SyncableRepo as ModProto
+
+        assert PkgProto is ModProto
+
+    def test_in_all_list(self) -> None:
+        import vds_git_orchestrator
+
+        assert "SyncableRepo" in vds_git_orchestrator.__all__

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

@@ -0,0 +1,241 @@
+# Google Sheets Orchestrator
+
+VDS standalone orchestrator for Google Sheets automation. Use `vds-cli google-sheets` for normal workflows;
+`vds-cli google-sheets` is available for development and direct debugging.
+
+## Requirements
+
+- Python 3.14+
+- Google Sheets API + Google Drive API enabled in your Google Cloud project
+
+## Installation
+
+```bash
+cd WHO-project/vds-scripts
+./scripts/worktree_uv.sh sync --project google_sheets_orchestrator
+```
+
+## Authentication
+
+### Service account (recommended)
+
+1. Create a service account JSON key and save it under the shared VDS config root (for example `<config-root>/google_credentials.json`, with `~/.vds/google_credentials.json` as the active Unix-like default).
+2. Share the target spreadsheet with the service account email (for private sheets).
+
+CLI usage:
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets read --spreadsheet-url <url> --sheet-name Sheet1 \
+  --auth-method service_account --credentials-path "$HOME/.vds/google_credentials.json"
+```
+
+### OAuth (user consent)
+
+1. Create OAuth credentials JSON and save it under the shared VDS config root (for example `<config-root>/gspread_oauth.json`, with `~/.vds/gspread_oauth.json` as the active Unix-like default).
+2. The first run will open a browser to authorize and cache credentials under that same config root.
+
+CLI usage:
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets read --spreadsheet-url <url> --sheet-name Sheet1 \
+  --auth-method oauth --oauth-credentials-path /path/to/shared-config/gspread_oauth.json
+```
+
+### API key (public sheets only)
+
+Set `VDS_GOOGLE_API_KEY` in the shared VDS env file, place the key under the shared VDS config root,
+or pass `--api-key`.
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets read --spreadsheet-url <url> --sheet-name Sheet1 \
+  --auth-method api_key --api-key "$VDS_GOOGLE_API_KEY"
+```
+
+> API key auth can only read public sheets via `open_by_key` / `open_by_url`.
+
+## Environment Variables
+
+```bash
+VDS_GOOGLE_CREDENTIALS_PATH=/path/to/shared-config/google_credentials.json
+VDS_GOOGLE_OAUTH_CREDENTIALS_PATH=/path/to/shared-config/gspread_oauth.json
+VDS_GOOGLE_API_KEY_PATH=/path/to/shared-config/google_api_key.txt
+VDS_GOOGLE_API_KEY=...your_api_key...
+VDS_GOOGLE_DEFAULT_AUTH_METHOD=service_account
+```
+
+## Global CLI Options
+
+All commands support the following global options:
+
+| Option | Description |
+|--------|-------------|
+| `--version` | Show CLI version and exit |
+| `--json-only` | Emit JSON output only (no Rich tables) |
+| `--reports/--no-reports` | Enable/disable report file generation |
+| `--structured-logs/--no-structured-logs` | Output structured JSON logs to stderr |
+| `--report-dir PATH` | Directory for run reports |
+| `--help` | Show help message |
+
+## Reports
+
+When `--reports` is enabled (default), each command writes a JSON report to the report directory
+(default: `~/.cache/vds-google-sheets-reports`). If `--markdown` is enabled (default), a companion
+Markdown summary is also written alongside the JSON file.
+
+## CLI Commands
+
+### Read data
+
+```bash
+# Read with Rich table output (default)
+vds-cli google-sheets read --spreadsheet-url <url> --sheet-name Sheet1
+
+# Read a limited range
+vds-cli google-sheets read --spreadsheet-url <url> --sheet-name Sheet1 --range A1:F10
+
+# Read with JSON output (for scripting)
+vds-cli google-sheets --json-only read --spreadsheet-url <url> --sheet-name Sheet1
+```
+
+### List worksheets
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets list-worksheets --spreadsheet-url <url>
+
+# JSON output
+vds-cli google-sheets --json-only list-worksheets --spreadsheet-url <url> | jq '.worksheets'
+```
+
+### Write values
+
+```bash
+# Write JSON array of arrays to a range
+vds-cli google-sheets write --spreadsheet-url <url> --sheet-name Sheet1 --range A1:B2 \
+  --values-json '[["A1","B1"],["A2","B2"]]'
+
+# Write from file
+vds-cli google-sheets write --spreadsheet-url <url> --sheet-name Sheet1 --range A1:B2 \
+  --values-file data.json
+```
+
+### Append rows
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets append --spreadsheet-url <url> --sheet-name Sheet1 \
+  --values-json '[["New","Row"]]'
+```
+
+### Update values (alias of write)
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets update --spreadsheet-url <url> --sheet-name Sheet1 --range A1:B2 \
+  --values-json '[["Updated","Values"]]'
+```
+
+### Clear range
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets clear --spreadsheet-url <url> --sheet-name Sheet1 --range A1:B10
+```
+
+### Create spreadsheet
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets create-spreadsheet --title "My New Spreadsheet"
+```
+
+### Create worksheet
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets create-worksheet --spreadsheet-url <url> --title "New Sheet" \
+  --rows 100 --cols 26
+```
+
+### Delete worksheet
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets delete-worksheet --spreadsheet-url <url> --sheet-name "Old Sheet"
+```
+
+### Export to file
+
+```bash
+# Export to CSV
+vds-cli google-sheets export --spreadsheet-url <url> --sheet-name Sheet1 --output data.csv
+
+# Export to Excel
+vds-cli google-sheets export --spreadsheet-url <url> --sheet-name Sheet1 --output data.xlsx --format xlsx
+```
+
+## JSON Output Mode
+
+Use `--json-only` for machine-readable output (ideal for scripting):
+
+```bash
+# Get worksheet list as JSON
+vds-cli google-sheets --json-only list-worksheets --spreadsheet-url <url> | jq '.worksheets'
+
+# Read sheet data as JSON
+vds-cli google-sheets --json-only read --spreadsheet-url <url> --sheet-name Sheet1 > data.json
+
+# Parse row count
+vds-cli google-sheets --json-only read --spreadsheet-url <url> --sheet-name Sheet1 | jq '.count'
+```
+
+## Structured Logging
+
+Enable JSON logs for monitoring/debugging:
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets --structured-logs read --spreadsheet-url <url> 2> logs.json
+```
+
+## VDS CLI Integration
+
+Access via the unified `vds-cli` interface:
+
+```bash
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets --help
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets read \
+  --spreadsheet-url <url> --sheet-name Sheet1
+
+# Pass-through global options
+./scripts/worktree_uv.sh run --project vds_cli vds-cli google-sheets -- --json-only read \
+  --spreadsheet-url <url> --sheet-name Sheet1 --range A1:F10
+```
+
+## Troubleshooting
+
+If `vds-cli google-sheets` reports `ModuleNotFoundError`, install the package:
+
+```bash
+cd WHO-project/vds-scripts/google_sheets_orchestrator
+uv pip install -e .
+```
+
+## API Reference
+
+### Python Usage
+
+```python
+from vds_google_sheets_orchestrator import GoogleSheetsClient, GoogleSheetsSettings
+
+# Using settings from the shared VDS env/config layer
+client = GoogleSheetsClient()
+
+# Read data
+data = client.read_sheet("https://docs.google.com/spreadsheets/d/...", "Sheet1")
+
+# Write data
+client.write_range("https://...", "Sheet1", "A1:B2", [["A1", "B1"], ["A2", "B2"]])
+
+# List worksheets
+sheets = client.list_worksheets("https://...")
+```
+.")
+```
+"A1", "B1"], ["A2", "B2"]])
+
+# List worksheets
+sheets = client.list_worksheets("https://...")
+```
+.")
+```