Huge overhaul

.env.common.example

@@ -0,0 +1,21 @@
+# =============================================================================
+# Common Configuration
+# =============================================================================
+# Loaded by every `dh` command, regardless of which group (docs, clients, db, ...) it's under.
+
+# Enable/disable spinner in the CLI output
+# SPINNER=true
+
+# =============================================================================
+# External Program Command Overrides
+# =============================================================================
+# Override the command used to invoke external programs
+# Format: <PROGRAM>_COMMAND=<command>
+#
+# Available programs: TSX, NPM, BASH, PYTHON, JAVA, DOTNET, JQ, GO
+#
+# Examples:
+#   TSX_COMMAND=npx -y tsx
+#   BASH_COMMAND=/usr/bin/bash
+#   PYTHON_COMMAND=python3.11
+#   JAVA_COMMAND=/usr/lib/jvm/java-21/bin/java

.env.example → .env.docs.example

@@ -1,12 +1,13 @@
 # =============================================================================
 # Required Configuration
 # =============================================================================
+# Loaded only for `dh docs ...` commands.
 
 # Client driver(s) to verify (comma-separated, e.g., 'java,typescript,python,bash')
 # CLIENT_DRIVERS=
 
 # Astra token for authentication
-# TOKEN=
+# ASTRA_TOKEN=
 
 # Test database API endpoint
 # API_ENDPOINT=
@@ -33,9 +34,6 @@
 # Whether to stop after the first test failure
 # BAIL=false
 
-# Enable/disable spinner in the CLI output
-# SPINNER=true
-
 # Comma-separated regex filters to select specific tests to run
 # FILTERS=
 
@@ -54,17 +52,3 @@
 #   TYPESCRIPT_ARTIFACT=@datastax/astra-db-ts@v2.0.0
 #   PYTHON_ARTIFACT=/path/to/local/package
 #   JAVA_ARTIFACT=com.datastax.astra:astra-db-java:2.1.0
-
-# =============================================================================
-# External Program Command Overrides
-# =============================================================================
-# Override the command used to invoke external programs
-# Format: <PROGRAM>_COMMAND=<command>
-#
-# Available programs: TSX, NPM, BASH, PYTHON, JAVA
-#
-# Examples:
-#   TSX_COMMAND=npx -y tsx
-#   BASH_COMMAND=/usr/bin/bash
-#   PYTHON_COMMAND=python3.11
-#   JAVA_COMMAND=/usr/lib/jvm/java-21/bin/java

.github/actions/_setup-clients-env/action.yml

@@ -0,0 +1,66 @@
+name: 'Setup clients environment'
+description: 'Installs the language toolchains needed to run client integration tests'
+
+inputs:
+  clients:
+    description: 'Comma-separated list of clients to test (e.g., java,typescript,python) or "all" for all clients'
+    required: true
+
+runs:
+  using: composite
+  steps:
+    # --- typescript ---
+    - name: Setup node
+      if: inputs.clients == 'all' || contains(inputs.clients, 'typescript')
+      uses: actions/setup-node@v4
+      with:
+        node-version: 'lts/*'
+        cache: 'npm'
+
+    - name: Verify node
+      if: inputs.clients == 'all' || contains(inputs.clients, 'typescript')
+      shell: bash
+      run: |
+        set -x
+        node --version
+        npm --version
+
+    # --- python ---
+    - name: Setup uv
+      if: inputs.clients == 'all' || contains(inputs.clients, 'python')
+      uses: astral-sh/setup-uv@v6
+
+    - name: Verify uv
+      if: inputs.clients == 'all' || contains(inputs.clients, 'python')
+      shell: bash
+      run: |
+        set -x
+        uv --version
+
+    # --- go ---
+    - name: Setup go
+      if: inputs.clients == 'all' || contains(inputs.clients, 'go')
+      uses: actions/setup-go@v5
+      with:
+        go-version: 'stable'
+
+    - name: Verify go
+      if: inputs.clients == 'all' || contains(inputs.clients, 'go')
+      shell: bash
+      run: |
+        set -x
+        go version
+
+    # --- dotnet ---
+    - name: Setup dotnet
+      if: inputs.clients == 'all' || contains(inputs.clients, 'csharp')
+      uses: actions/setup-dotnet@v5
+      with:
+        dotnet-version: '8.0.x'
+
+    - name: Verify dotnet
+      if: inputs.clients == 'all' || contains(inputs.clients, 'csharp')
+      shell: bash
+      run: |
+        set -x
+        dotnet --list-sdks

.github/actions/use-dh/action.yml → .github/actions/_setup-docs-env/action.yml

@@ -1,5 +1,5 @@
-name: 'setup-dh'
-description: 'Builds the `dh` cli + installs any required dependencies'
+name: 'Setup docs environment'
+description: 'Clones the docs repo and installs the language toolchains needed to run docs examples'
 
 inputs:
   docs-repo:
@@ -18,20 +18,6 @@ inputs:
     description: 'Install jq'
     required: false
     default: 'false'
-  args:
-    description: 'Args to pass to dh'
-    required: true
-  allow-failures:
-    description: 'Whether to allow test failures without failing the entire workflow'
-    default: 'false'
-
-outputs:
-  dh-cli-path:
-    description: 'Path to the built dh jar file'
-    value: ${{ steps.build-cli.outputs.dh-cli-path }}
-  failed_tests:
-    description: 'Whether any tests failed'
-    value: ${{ steps.run-tests.outputs.failed_tests }}
 
 runs:
   using: composite
@@ -44,25 +30,25 @@ runs:
         BRANCH="main"
 
         REPO_INPUT="${{ inputs.docs-repo }}"
-        
+
         if [[ -n "$REPO_INPUT" ]]; then
           if [[ "$REPO_INPUT" == *"@"* ]]; then
             LEFT="${REPO_INPUT%%@*}"
             RIGHT="${REPO_INPUT#*@}"
-        
+
             [[ -n "$LEFT" ]] && REPO_PATH="$LEFT"
             [[ -n "$RIGHT" ]] && BRANCH="$RIGHT"
           else
             REPO_PATH="$REPO_INPUT"
           fi
         fi
-        
+
         EXAMPLES_PATH="${{ inputs.examples-path }}"
-        
+
         echo "repo-path=$REPO_PATH" >> $GITHUB_OUTPUT
         echo "branch=$BRANCH" >> $GITHUB_OUTPUT
         echo "examples-path=$EXAMPLES_PATH" >> $GITHUB_OUTPUT
-        
+
         echo "Repository: '$REPO_PATH'"
         echo "Branch: '$BRANCH'"
         echo "Examples path: '$EXAMPLES_PATH'"
@@ -83,29 +69,15 @@ runs:
       run: |
         DOCS_PATH="${{ github.workspace }}/docs-repo"
         EXAMPLES_FOLDER="$DOCS_PATH/${{ steps.parse-repo.outputs.examples-path }}"
-        
+
         if [ ! -d "$EXAMPLES_FOLDER" ]; then
           echo "ERROR: Examples folder not found: $EXAMPLES_FOLDER"
           exit 1
         fi
-        
+
         echo "EXAMPLES_FOLDER=$EXAMPLES_FOLDER" >> $GITHUB_ENV
         echo "Documentation cloned to: $DOCS_PATH"
 
-    # --- java ---
-    - name: Setup java
-      uses: actions/setup-java@v4
-      with:
-        distribution: 'temurin'
-        java-version: '25'
-        cache: 'gradle'
-
-    - name: Verify java
-      shell: bash
-      run: |
-        set -x
-        java --version
-
     # --- typescript ---
     - name: Setup node
       if: inputs.setup-languages == 'all' || contains(inputs.setup-languages, 'typescript')
@@ -121,7 +93,6 @@ runs:
         set -x
         node --version
         npm --version
-        npx tsx --version
 
     - name: Setup + verify tsx
       if: inputs.setup-languages == 'all' || contains(inputs.setup-languages, 'typescript')
@@ -173,40 +144,3 @@ runs:
         set -x
         sudo apt-get update && sudo apt-get install -y jq
         jq --version
-
-    # --- actually use dh ---
-    - name: Use dh
-      shell: bash
-      id: run-tests
-      run: |
-        set -x
-
-        export SPINNER=false
-        source astra-client-docs-tests/scripts/dev-alias.sh --no-compgen
-
-        set +e
-
-        dh ${{ inputs.args }}
-        exit_code=$?
-
-        case $exit_code in
-          0)
-            echo "failed_tests=false" >> $GITHUB_OUTPUT
-            ;;
-          100)
-            echo "failed_tests=true" >> $GITHUB_OUTPUT
-            if [[ "${{ inputs.allow-failures }}" == 'false' ]]; then
-              exit 100
-            fi
-            ;;
-          *)
-            exit $exit_code
-            ;;
-        esac
-
-    - name: Print logs on failure
-      if: always() && steps.run-tests.outputs.failed_tests == 'true'
-      shell: bash
-      run: |
-        set -x
-        cat astra-client-docs-tests/.docs_tests_temp/logs/* || echo "No logs found"

.github/actions/_use-dh/action.yml

@@ -0,0 +1,72 @@
+name: 'Actually use dh'
+description: 'Builds and runs the `dh` cli'
+
+inputs:
+  args:
+    description: 'Args to pass to dh'
+    required: true
+  allow-failures:
+    description: 'Whether to allow test failures without failing the entire workflow'
+    default: 'false'
+
+outputs:
+  dh-cli-path:
+    description: 'Path to the built dh jar file'
+    value: ${{ steps.build-cli.outputs.dh-cli-path }}
+  failed_tests:
+    description: 'Whether any tests failed'
+    value: ${{ steps.run-tests.outputs.failed_tests }}
+
+runs:
+  using: composite
+  steps:
+    # --- java ---
+    - name: Setup java
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '25'
+        cache: 'gradle'
+
+    - name: Verify java
+      shell: bash
+      run: |
+        set -x
+        java --version
+
+    # --- actually use dh ---
+    - name: Use dh
+      shell: bash
+      id: run-tests
+      run: |
+        set -x
+
+        export SPINNER=false
+        source astra-client-docs-tests/scripts/dev-alias.sh --no-compgen
+
+        set +e
+
+        dh ${{ inputs.args }}
+        exit_code=$?
+
+        case $exit_code in
+          0)
+            echo "failed_tests=false" >> $GITHUB_OUTPUT
+            ;;
+          100)
+            echo "failed_tests=true" >> $GITHUB_OUTPUT
+            if [[ "${{ inputs.allow-failures }}" == 'false' ]]; then
+              exit 100
+            fi
+            ;;
+          *)
+            exit $exit_code
+            ;;
+        esac
+
+    - name: Print logs on failure
+      if: always() && steps.run-tests.outputs.failed_tests == 'true'
+      shell: bash
+      run: |
+        set -x
+        cat astra-client-docs-tests/.dh_temp/logs/* || echo "No logs found"

.github/actions/test-clients/action.yml

@@ -0,0 +1,46 @@
+inputs:
+  clients:
+    description: 'Comma-separated list of clients to test (e.g., java,typescript,python) or "all" for all clients'
+    required: true
+  args:
+    description: 'Additional arguments to pass to dh'
+    default: ''
+  db-token:
+    description: 'Astra token for authentication'
+    required: true
+  db-endpoint:
+    description: 'API endpoint for testing'
+    required: true
+  allow-failures:
+    description: 'Whether to allow test failures without failing the entire workflow'
+    default: 'false'
+
+outputs:
+  failed_tests:
+    description: 'Whether any tests failed'
+    value: ${{ steps.run-tests.outputs.failed_tests }}
+
+runs:
+  using: composite
+  steps:
+    - name: Checkout docs testing repository
+      uses: actions/checkout@v4
+      with:
+        repository: 'datastax/astra-client-docs-tests'
+        path: astra-client-docs-tests
+
+    - name: Setup clients env
+      uses: ./astra-client-docs-tests/.github/actions/_setup-clients-env
+      with:
+        clients: ${{ inputs.clients }}
+
+    - name: Run client integration tests
+      id: run-tests
+      uses: ./astra-client-docs-tests/.github/actions/_use-dh
+      env:
+        ASTRA_TOKEN: ${{ inputs.db-token }}
+        API_ENDPOINT: ${{ inputs.db-endpoint }}
+      with:
+        allow-failures: ${{ inputs.allow-failures }}
+        args: |
+          clients test ${{ inputs.clients }} ${{ inputs.args }}