Add GitHub API Wrapper Script and Documentation

.github/workflows/test-bash-framework.yml

@@ -3,9 +3,9 @@ name: Test Bash Framework
 on:
   push:
     branches: [main]
-    paths-ignore: [ 'docs/**', '**/*.md' ]
+    paths: [ 'scripts-demo/**', 'tests/shell/bash/**' ]
   pull_request:
-    paths-ignore: [ 'docs/**', '**/*.md' ]
+    paths: [ 'scripts-demo/**', 'tests/shell/bash/**' ]
   workflow_dispatch:
 
 jobs:
@@ -21,14 +21,8 @@ jobs:
           - os: ubuntu-latest
             shell-name: bash
             shell-cmd: bash
-          - os: ubuntu-latest
-            shell-name: zsh
-            shell-cmd: zsh
 
-          # macOS - bash and zsh
-          - os: macos-latest
-            shell-name: bash
-            shell-cmd: bash
+          # macOS - zsh
           - os: macos-latest
             shell-name: zsh
             shell-cmd: zsh
@@ -42,13 +36,6 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Install zsh (Ubuntu only)
-        if: matrix.os == 'ubuntu-latest' && matrix.shell-name == 'zsh'
-        shell: bash
-        run: |
-          sudo apt-get update
-          sudo apt-get install -y zsh
-
       - name: Run demo tests (excluding intentional failures)
         shell: bash
         working-directory: tests/shell/bash

.github/workflows/test-bash-scripts.yml

@@ -3,9 +3,9 @@ name: Test Bash Scripts
 on:
   push:
     branches: [main]
-    paths-ignore: [ 'docs/**', '**/*.md' ]
+    paths: [ 'scripts/**', 'tests/shell/bash/**' ]
   pull_request:
-    paths-ignore: [ 'docs/**', '**/*.md' ]
+    paths: [ 'scripts/**', 'tests/shell/bash/**' ]
   workflow_dispatch:
 
 jobs:
@@ -34,7 +34,8 @@ jobs:
         working-directory: tests/shell/bash
         run: |
           ./test-runner.sh \
-            --fail-fast true
+            --fail-fast true \
+            --verbose
 
       - name: Test results summary
         if: always()

.github/workflows/test-framework-compose-filename-manual.yml

@@ -0,0 +1,57 @@
+name: "Call action manually: framework compose filename"
+
+on:
+  workflow_dispatch:
+    inputs:
+      runner:
+        description: "Runner to use (e.g. ubuntu-latest, ubuntu-22.04, windows-latest, etc)"
+        type: string
+        required: false
+        default: ubuntu-latest
+      version:
+        description: 'OpenDAQ version (if not set, resolves to latest from openDAQ/openDAQ)'
+        required: false
+      platform:
+        description: 'Target platform (if not set, auto-detected)'
+        required: false
+      packaging:
+        description: 'Packaging format for cpack (if not set, uses runner OS name)'
+        required: false
+
+jobs:
+  test-compose-filename-manually:
+    runs-on: ${{ inputs.runner }}
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Compose openDAQ framework filename
+      id: call-framework-compose-filename
+      uses: ./framework-compose-filename
+      with:
+        version: ${{ inputs.version }}
+        platform: ${{ inputs.platform }}
+        packaging: ${{ inputs.packaging }}
+
+    - name: Display Results
+      shell: bash
+      run: |
+        echo "╔══════════════════════════════════════════════════════════════════════════════╗"
+        echo "║                     Package Filename Composition Results                     ║"
+        echo "╠══════════════════════════════════════════════════════════════════════════════╣"
+        echo "║ 🏷️  Version (full):    ${{ steps.call-framework-compose-filename.outputs.version }}"
+        echo "║    ├─ Major:           ${{ steps.call-framework-compose-filename.outputs.version-major }}"
+        echo "║    ├─ Minor:           ${{ steps.call-framework-compose-filename.outputs.version-minor }}"
+        echo "║    ├─ Patch:           ${{ steps.call-framework-compose-filename.outputs.version-patch }}"
+        echo "║    ├─ Suffix:          ${{ steps.call-framework-compose-filename.outputs.version-suffix || '*** NOT SET ***' }}"
+        echo "║    └─ Hash:            ${{ steps.call-framework-compose-filename.outputs.version-hash || '*** NOT SET ***' }}"
+        echo "╠══════════════════════════════════════════════════════════════════════════════╣"
+        echo "║ 🖥️  Platform (full):   ${{ steps.call-framework-compose-filename.outputs.platform }}"
+        echo "║    ├─ OS Name:         ${{ steps.call-framework-compose-filename.outputs.platform-os-name }}"
+        echo "║    ├─ OS Version:      ${{ steps.call-framework-compose-filename.outputs.platform-os-version }}"
+        echo "║    └─ Architecture:    ${{ steps.call-framework-compose-filename.outputs.platform-os-arch }}"
+        echo "╠══════════════════════════════════════════════════════════════════════════════╣"
+        echo "║ 📦 Packaging:          ${{ steps.call-framework-compose-filename.outputs.packaging }}"
+        echo "╠══════════════════════════════════════════════════════════════════════════════╣"
+        echo "║ 📄 Filename:           ${{ steps.call-framework-compose-filename.outputs.filename }}"
+        echo "╚══════════════════════════════════════════════════════════════════════════════╝"

.github/workflows/test-framework-download-release-manual.yml

@@ -0,0 +1,82 @@
+name: Test Download Release Asset
+
+on:
+  workflow_dispatch:
+    inputs:
+      runner-os:
+        description: 'Runner OS to use'
+        required: true
+        type: string
+        default: 'ubuntu-latest'
+
+      version:
+        description: 'Release version (e.g., v3.20.4) or "latest"'
+        required: false
+        type: string
+        default: 'latest'
+
+      platform:
+        description: 'Target platform (e.g., ubuntu22.04-x86_64, win64) or leave empty for auto-detect'
+        required: false
+        type: string
+        default: ''
+
+      packaging:
+        description: 'Package format override (e.g., deb, exe, tar.gz, zip) or leave empty for auto-detect'
+        required: false
+        type: string
+        default: ''
+
+      asset-pattern:
+        description: 'Custom glob pattern to filter assets (overrides auto-detection)'
+        required: false
+        type: string
+        default: ''
+
+      output-dir:
+        description: 'Output directory for downloaded assets (leave empty for runner.temp)'
+        required: false
+        type: string
+        default: ''
+
+      verbose:
+        description: 'Enable verbose output'
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  download-release:
+    name: Download on ${{ inputs.runner-os }}
+    runs-on: ${{ inputs.runner-os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Download OpenDAQ release asset
+        id: download
+        uses: ./framework-download-release
+        with:
+          version: ${{ inputs.version }}
+          platform: ${{ inputs.platform }}
+          packaging: ${{ inputs.packaging }}
+          asset-pattern: ${{ inputs.asset-pattern }}
+          output-dir: ${{ inputs.output-dir }}
+          verbose: ${{ inputs.verbose }}
+
+      - name: Display results
+        shell: bash
+        run: |
+          echo "=== Download Results ==="
+          echo ""
+          echo "📦 Asset: ${{ steps.download.outputs.asset-filename }}"
+          echo "📍 Path: ${{ steps.download.outputs.asset }}"
+          echo "📂 Directory: ${{ steps.download.outputs.asset-dir }}"
+          echo ""
+          echo "🏷️  Version: ${{ steps.download.outputs.version }}"
+          echo "🖥️  Platform: ${{ steps.download.outputs.platform }}"
+          echo "📦 Packaging: ${{ steps.download.outputs.packaging }}"
+          echo ""
+          echo "📊 Size: ${{ steps.download.outputs.asset-filesize }} bytes"
+          echo "🔐 SHA256: ${{ steps.download.outputs.asset-checksum }}"

docs/scripts/shell/bash/CONVENTIONS.md

@@ -184,7 +184,70 @@ Each script module uses consistent prefix:
 | `version-format.sh` | `daq_version_` | `daq_version_compose` |
 | `platform-format.sh` | `daq_platform_` | `daq_platform_detect` |
 | `packaging-format.sh` | `daq_packaging_` | `daq_packaging_detect_from_cpack` |
-| `api-github-gh.sh` | `daq_gh_` | `daq_gh_release_list` |
+| `api-github-gh.sh` | `daq_api_gh_` | `daq_api_gh_version_latest` |
+
+## Special Module Naming Cases
+
+### API Wrapper Modules
+
+Modules that wrap external APIs or services may use extended prefixes for clarity.
+
+**Pattern**: `api-<service>-<tool>.sh` with prefix `daq_api_<service>_`
+
+**When to use**:
+- Module wraps external API or CLI tool
+- Need to distinguish from domain modules
+- Additional context improves API clarity
+
+**Examples**:
+
+```bash
+# GitHub API wrapper
+api-github-gh.sh          # Prefix: daq_api_gh_
+  daq_api_gh_version_latest()
+  daq_api_gh_version_list()
+
+# Hypothetical examples
+api-gitlab-cli.sh         # Prefix: daq_api_gitlab_
+api-docker-sdk.sh         # Prefix: daq_api_docker_
+```
+
+**Comparison with domain modules**:
+
+| Type | File Pattern | Prefix Pattern | Use Case |
+|------|--------------|----------------|----------|
+| Domain module | `<domain>-format.sh` | `daq_<domain>_` | Data format parsing/composition |
+| API wrapper | `api-<service>-<tool>.sh` | `daq_api_<service>_` | External service integration |
+
+**Example distinction**:
+
+```bash
+# Domain module - formats and parsing
+version-format.sh → daq_version_compose()    # Create version string
+version-format.sh → daq_version_parse()      # Parse version string
+
+# API wrapper - external service calls
+api-github-gh.sh → daq_api_gh_version_latest()   # Fetch from GitHub API
+api-github-gh.sh → daq_api_gh_version_list()     # List versions from GitHub
+```
+
+**Rationale**:
+- Prefix `daq_api_gh_` clearly indicates GitHub API wrapper
+- Distinguishes from potential `daq_github_` (format-related functions)
+- Prevents confusion between API calls and format operations
+- Allows both modules to coexist: `github-format.sh` (formats) and `api-github-gh.sh` (API)
+
+**Namespace protection**:
+
+```bash
+# Safe to source together
+source github-format.sh    # Hypothetical: daq_github_parse()
+source api-github-gh.sh    # Actual: daq_api_gh_version_latest()
+
+# No naming conflicts
+daq_github_parse "v1.0.0"              # Format parsing
+daq_api_gh_version_latest              # API call
+```
 
 ## Namespace Protection
 
@@ -228,10 +291,10 @@ daq_package_compose --version "$version" --platform "$platform"
 
 Each module should have one clear purpose:
 
-- ✅ `version-format.sh` - handles version strings
-- ✅ `platform-format.sh` - handles platform identifiers
-- ✅ `packaging-format.sh` - handles package extensions
-- ⌠`utils.sh` - too generic, unclear purpose
+- `version-format.sh` - handles version strings
+- `platform-format.sh` - handles platform identifiers
+- `packaging-format.sh` - handles package extensions
+- `utils.sh` - too generic, unclear purpose
 
 ### Focused API
 
@@ -299,8 +362,8 @@ daq_packaging_validate_generator()   # New: validate generator name
 
 Use this checklist when creating or reviewing scripts:
 
-- [ ] All public functions start with `daq_<module>_`
-- [ ] All private functions start with `__daq_<module>_`
+- [ ] All public functions start with `daq_<module>_` or `daq_api_<service>_` (for API wrappers)
+- [ ] All private functions start with `__daq_<module>_` or `__daq_api_<service>_` (for API wrappers)
 - [ ] All public constants start with `OPENDAQ_<MODULE>_`
 - [ ] All private variables start with `__DAQ_<MODULE>_`
 - [ ] Match variables start with `__MATCH_`
@@ -323,6 +386,7 @@ Following these conventions provides:
 
 ## See Also
 
-- [packaginh-format.sh](packaging-format/README.md) - Example implementation
-- [platform-format.sh](platform-format/README.md) - Example implementation
-- [version-format.sh](version-format/README.md) - Example implementation
+- [version-format.sh](version-format/README.md) - Domain module example
+- [platform-format.sh](platform-format/README.md) - Domain module example
+- [packaging-format.sh](packaging-format/README.md) - Domain module example
+- [api-github-gh.sh](api-github-gh/README.md) - API wrapper module example