action.yml

name: "Setup Kapi CLI"
description: "Install the kapi CLI for CI workflows — downloads, verifies, caches, and configures the binary"
branding:
  icon: "globe"
  color: "blue"

inputs:
  version:
    description: "Kapi CLI version (e.g. '1.1.0' or 'latest' for the newest stable CLI release)"
    required: false
    default: "latest"
  token:
    description: "GitHub token used for release downloads and API rate limits. The built-in GITHUB_TOKEN is sufficient now that neokapi/neokapi is public."
    required: false
    default: ${{ github.token }}
  plugins:
    description: >-
      Newline- or comma-separated plugin refs to install, as the registry
      names them (e.g. 'bowrain', 'okapi-bridge'). The 'kapi-' binary prefix
      is accepted and stripped ('kapi-bowrain' → 'bowrain'). Defaults to
      'bowrain' so server-connected projects work out of the box; pass '' to
      install nothing.
    required: false
    default: "bowrain"
  auth-token:
    description: "Bowrain server JWT auth token (exported as BOWRAIN_AUTH_TOKEN)"
    required: false
    default: ""
  server:
    description: "Bowrain server URL (exported as BOWRAIN_SERVER_URL)"
    required: false
    default: ""
  cache-tm:
    description: >-
      Restore and persist the project translation memory across CI runs via the
      job cache. The TM is derived state kept out of git (AD-009): the latest
      branch TM is restored at setup, and the grown TM is saved back at job end
      under a run-unique key, so leverage compounds without committing anything.
      A cold cache is fine — kapi rebuilds the TM from the committed translations.
      Runs only when a kapi.yaml recipe (or legacy *.kapi) is present. Set 'false' to disable.
    required: false
    default: "true"
  project-dir:
    description: "Directory holding the kapi.yaml project (recipe + state) for the TM cache. Default: repository root."
    required: false
    default: "."

outputs:
  version:
    description: "Installed kapi CLI version (e.g. '0.5.0')"
    value: ${{ steps.resolve.outputs.version }}
  cache-hit:
    description: "Whether the plugin cache was hit"
    value: ${{ steps.plugin-cache.outputs.cache-hit }}

runs:
  using: "composite"
  steps:
    # 1. Resolve version
    - name: Resolve version
      id: resolve
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.token }}
        INPUT_VERSION: ${{ inputs.version }}
        ACTION_PATH: ${{ github.action_path }}
      run: |
        VERSION=$("${ACTION_PATH}/scripts/resolve-version.sh" "${INPUT_VERSION}")
        echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
        echo "Resolved version: ${VERSION}"

    # 2. Detect platform
    - name: Detect platform
      id: platform
      shell: bash
      env:
        ACTION_PATH: ${{ github.action_path }}
      run: |
        source "${ACTION_PATH}/scripts/platform.sh"
        echo "os=${GOOS}" >> "$GITHUB_OUTPUT"
        echo "arch=${GOARCH}" >> "$GITHUB_OUTPUT"
        echo "ext=${ARCHIVE_EXT}" >> "$GITHUB_OUTPUT"
        echo "Platform: ${GOOS}/${GOARCH} (archive: .${ARCHIVE_EXT})"

    # 3. Restore binary cache
    - name: Restore binary cache
      id: binary-cache
      uses: actions/cache@v5
      with:
        path: ${{ runner.temp }}/setup-kapi
        key: kapi-${{ steps.resolve.outputs.version }}-${{ runner.os }}-${{ runner.arch }}

    # 4. Download + verify (on cache miss)
    - name: Download and verify
      if: steps.binary-cache.outputs.cache-hit != 'true'
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.token }}
        ACTION_PATH: ${{ github.action_path }}
        VERSION: ${{ steps.resolve.outputs.version }}
        PLATFORM_OS: ${{ steps.platform.outputs.os }}
        PLATFORM_ARCH: ${{ steps.platform.outputs.arch }}
        PLATFORM_EXT: ${{ steps.platform.outputs.ext }}
        INSTALL_DIR: ${{ runner.temp }}/setup-kapi
      run: |
        "${ACTION_PATH}/scripts/download-verify.sh" \
          "${VERSION}" \
          "${PLATFORM_OS}" \
          "${PLATFORM_ARCH}" \
          "${PLATFORM_EXT}" \
          "${INSTALL_DIR}"

    # 5. Add to PATH
    - name: Add to PATH
      shell: bash
      env:
        INSTALL_DIR: ${{ runner.temp }}/setup-kapi
      run: echo "${INSTALL_DIR}" >> "$GITHUB_PATH"

    # 6. Verify installation
    - name: Verify installation
      shell: bash
      run: kapi version

    # 7. Configure bowrain server auth (optional)
    - name: Configure auth
      if: inputs.auth-token != ''
      shell: bash
      env:
        INPUT_AUTH_TOKEN: ${{ inputs.auth-token }}
        INPUT_SERVER: ${{ inputs.server }}
      run: |
        echo "BOWRAIN_AUTH_TOKEN=${INPUT_AUTH_TOKEN}" >> "$GITHUB_ENV"
        if [ -n "${INPUT_SERVER}" ]; then
          echo "BOWRAIN_SERVER_URL=${INPUT_SERVER}" >> "$GITHUB_ENV"
        fi
        echo "Auth configured for kapi"

    # 8. Compute plugin hash
    - name: Compute plugin hash
      if: inputs.plugins != ''
      id: plugin-hash
      shell: bash
      env:
        INPUT_PLUGINS: ${{ inputs.plugins }}
      run: |
        HASH=$(echo "${INPUT_PLUGINS}" | sha256sum | awk '{print $1}' 2>/dev/null || echo "${INPUT_PLUGINS}" | shasum -a 256 | awk '{print $1}')
        echo "hash=${HASH}" >> "$GITHUB_OUTPUT"

    # 9. Restore plugin cache
    - name: Restore plugin cache
      if: inputs.plugins != ''
      id: plugin-cache
      uses: actions/cache@v5
      with:
        # kapi installs plugins under $XDG_DATA_HOME/kapi/plugins — i.e.
        # ~/.local/share/kapi/plugins when XDG_DATA_HOME is unset, as it is on a
        # runner. The old ~/.config/kapi/plugins is the CONFIG dir: nothing was
        # ever written there, so the cache saved an empty path and every run
        # re-downloaded every plugin.
        path: ~/.local/share/kapi/plugins
        key: kapi-plugins-${{ steps.plugin-hash.outputs.hash }}-${{ runner.os }}-${{ runner.arch }}
        restore-keys: |
          kapi-plugins-

    # 10. Install plugins (on cache miss)
    - name: Install plugins
      if: inputs.plugins != '' && steps.plugin-cache.outputs.cache-hit != 'true'
      shell: bash
      env:
        INPUT_PLUGINS: ${{ inputs.plugins }}
      run: |
        # Normalize: replace commas with newlines, trim whitespace, skip empty
        # lines, and strip the 'kapi-' binary prefix — the registry names the
        # plugin 'bowrain' while its binary and archives are 'kapi-bowrain',
        # so both spellings should install.
        PLUGINS=$(echo "${INPUT_PLUGINS}" | tr ',' '\n' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//;s/^kapi-//' | grep -v '^$')
        while IFS= read -r plugin; do
          echo "Installing plugin: ${plugin}"
          kapi plugins install "${plugin}"
        done <<< "${PLUGINS}"

    # 11. Detect a kapi project — a committed kapi.yaml recipe (or legacy *.kapi). The TM cache only
    #     runs where there is a project TM to persist (the .kapi/ state dir is
    #     gitignored, so it may not exist yet; the recipe is the committed signal).
    - name: Detect kapi project
      id: detect-project
      if: inputs.cache-tm != 'false'
      shell: bash
      env:
        PROJECT_DIR: ${{ inputs.project-dir }}
      run: |
        if ls "${PROJECT_DIR}"/kapi.yaml >/dev/null 2>&1 || ls "${PROJECT_DIR}"/*.kapi >/dev/null 2>&1; then
          echo "found=true" >> "$GITHUB_OUTPUT"
        else
          echo "found=false (no kapi.yaml recipe (or legacy *.kapi) in ${PROJECT_DIR}); skipping TM cache" >&2
          echo "found=false" >> "$GITHUB_OUTPUT"
        fi

    # 12. Restore/persist the project TM across runs via the job cache. The TM is
    #     derived state kept out of git (AD-009): restore the latest branch TM at
    #     setup, and — because the key is run-unique — actions/cache saves the
    #     grown TM at job end via its own post step. No git writes, no locking
    #     (additive + rebuildable, last-write-wins); a cold cache rebuilds from
    #     committed content. Covers the current .kapi/tm.db and the .kapi/cache/
    #     derived stores.
    - name: Restore project TM cache
      if: inputs.cache-tm != 'false' && steps.detect-project.outputs.found == 'true'
      uses: actions/cache@v5
      with:
        path: |
          ${{ inputs.project-dir }}/.kapi/tm.db
          ${{ inputs.project-dir }}/.kapi/cache
        key: kapi-tm-${{ runner.os }}-${{ github.ref_name }}-${{ github.run_id }}
        restore-keys: |
          kapi-tm-${{ runner.os }}-${{ github.ref_name }}-
          kapi-tm-${{ runner.os }}-