@ngocsangairvds/vsaf 4.1.7 → 4.1.9

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

@@ -1,327 +0,0 @@
-"""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

@@ -1,132 +0,0 @@
-"""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

@@ -1,241 +0,0 @@
-# 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://...")
-```
-.")
-```