update-cli-coverage.yml

name: Update CLI Coverage

on:
  # A push to main can run before release-please tags the release.
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'PR number to use for context (leave empty to use most recent merged PR)'
        required: false
        type: string

permissions:
  contents: read

concurrency:
  group: update-cli-coverage
  cancel-in-progress: false

jobs:
  prefetch:
    if: github.repository == 'kernel/kernel-go-sdk'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
      pull-requests: read
    outputs:
      sha: ${{ steps.pr-info.outputs.merge_sha || github.sha }}
      version: ${{ steps.sdk-version.outputs.version }}
      module: ${{ steps.sdk-version.outputs.module }}
      author: ${{ steps.sdk-version.outputs.author }}
      old_version: ${{ steps.sdk-diff.outputs.old_version }}
      context_artifact_id: ${{ steps.upload-context.outputs.artifact-id }}
    steps:
      - name: Generate API read token
        id: api-read-token
        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
        with:
          app-id: ${{ secrets.ADMIN_APP_ID }}
          private-key: ${{ secrets.ADMIN_APP_PRIVATE_KEY }}
          owner: kernel
          repositories: kernel
          permission-contents: read

      - name: Get PR info for manual dispatch
        id: pr-info
        if: github.event_name == 'workflow_dispatch'
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER_INPUT: ${{ inputs.pr_number }}
        run: |
          if [ -n "$PR_NUMBER_INPUT" ]; then
            if [[ ! "$PR_NUMBER_INPUT" =~ ^[0-9]+$ ]]; then
              echo "::error::pr_number must be a pull request number."
              exit 1
            fi
            # Use provided PR number
            PR_NUMBER="$PR_NUMBER_INPUT"
            echo "Using provided PR number: $PR_NUMBER"
          else
            # Get most recent merged PR
            PR_NUMBER=$(gh pr list --repo ${{ github.repository }} --state merged --limit 1 --json number --jq '.[0].number')
            echo "Using most recent merged PR: $PR_NUMBER"
          fi
          
          if [ -z "$PR_NUMBER" ]; then
            echo "No PR found, will use HEAD commit"
            echo "has_pr=false" >> $GITHUB_OUTPUT
          else
            # Get PR details
            PR_DATA=$(gh pr view "$PR_NUMBER" --repo ${{ github.repository }} --json mergeCommit,author,title)
            MERGE_SHA=$(echo "$PR_DATA" | jq -r '.mergeCommit.oid // empty')
            PR_AUTHOR=$(echo "$PR_DATA" | jq -r '.author.login // empty')
            PR_TITLE=$(echo "$PR_DATA" | jq -r '.title // empty')
            
            echo "PR #$PR_NUMBER: $PR_TITLE"
            echo "Merge commit: $MERGE_SHA"
            echo "Author: $PR_AUTHOR"
            
            echo "has_pr=true" >> $GITHUB_OUTPUT
            echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
            echo "merge_sha=$MERGE_SHA" >> $GITHUB_OUTPUT
            echo "pr_author=$PR_AUTHOR" >> $GITHUB_OUTPUT
          fi

      - name: Checkout SDK repo
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          # The SDK diff starts at CLI main's version, which can be several tags back.
          fetch-depth: 0
          # For manual dispatch with a specific PR, checkout the merge commit
          ref: ${{ steps.pr-info.outputs.merge_sha || github.sha }}

      - name: Checkout context encryption certificate
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          path: updater
          sparse-checkout: .github/keys
          persist-credentials: false

      - name: Setup Go
        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
        with:
          go-version: 'stable'
          cache: false

      - name: Get SDK version info
        id: sdk-version
        env:
          RELEASE_TAG: ${{ github.event.release.tag_name }}
        run: |
          # Use the published release, else the latest tag, else the commit SHA
          LATEST_TAG=${RELEASE_TAG:-$(git describe --tags --abbrev=0 2>/dev/null || echo "")}
          if [ -n "$LATEST_TAG" ]; then
            echo "version=$LATEST_TAG" >> $GITHUB_OUTPUT
            echo "SDK version: $LATEST_TAG"
          else
            CURRENT_SHA="${{ steps.pr-info.outputs.merge_sha || github.sha }}"
            echo "version=$CURRENT_SHA" >> $GITHUB_OUTPUT
            echo "SDK version: $CURRENT_SHA (no tag)"
          fi
          
          # Get the module path from go.mod
          MODULE_PATH=$(head -1 go.mod | awk '{print $2}')
          echo "module=$MODULE_PATH" >> $GITHUB_OUTPUT
          echo "SDK module: $MODULE_PATH"
          
          # Determine the commit author (from PR info for manual dispatch, or from push event)
          if [ -n "${{ steps.pr-info.outputs.pr_author }}" ]; then
            echo "author=${{ steps.pr-info.outputs.pr_author }}" >> $GITHUB_OUTPUT
          else
            echo "author=${{ github.event.head_commit.author.username || github.actor }}" >> $GITHUB_OUTPUT
          fi

      - name: Compute SDK diff since CLI main's version
        id: sdk-diff
        run: |
          context="$RUNNER_TEMP/cli-coverage-context"
          mkdir -p "$context/api"
          # The report replaces the PR description, so audit every release since
          # the SDK version on CLI main, not only the ones since the last run.
          git clone -q --depth=1 https://github.com/kernel/cli.git "$RUNNER_TEMP/cli-main"
          OLD_SDK_VERSION=$(go mod edit -json "$RUNNER_TEMP/cli-main/go.mod" \
            | jq -er '.Require[] | select(.Path == "github.com/kernel/kernel-go-sdk") | .Version')
          echo "CLI main uses SDK version: $OLD_SDK_VERSION"
          echo "old_version=$OLD_SDK_VERSION" >> $GITHUB_OUTPUT

          NEW_SDK_VERSION="${{ steps.sdk-version.outputs.version }}"
          echo "New SDK version: $NEW_SDK_VERSION"

          # Compute the diff between old and new SDK versions
          # This gives the agent a focused view of what changed
          if git diff "$OLD_SDK_VERSION".."$NEW_SDK_VERSION" -- api.md '*.go' ':!*_test.go' ':!internal/*' > "$context/sdk-diff.patch" 2>/dev/null; then
            DIFF_LINES=$(wc -l < "$context/sdk-diff.patch")
            echo "SDK diff: $DIFF_LINES lines"
            if [ "$DIFF_LINES" -eq 0 ]; then
              echo "No SDK changes between versions (diff is empty)"
            fi
          else
            echo "Could not compute SDK diff (old version tag may not exist), creating empty diff"
            echo "" > "$context/sdk-diff.patch"
          fi

          utc_date() {
            TZ=UTC git log -1 --date=format-local:%Y-%m-%dT%H:%M:%SZ --format=%cd "$1"
          }
          echo "old_date=$(utc_date "$OLD_SDK_VERSION" 2>/dev/null || true)" >> $GITHUB_OUTPUT
          echo "new_date=$(utc_date HEAD)" >> $GITHUB_OUTPUT

      - name: Fetch API spec
        env:
          GH_TOKEN: ${{ steps.api-read-token.outputs.token }}
          OLD_DATE: ${{ steps.sdk-diff.outputs.old_date }}
          NEW_DATE: ${{ steps.sdk-diff.outputs.new_date }}
        run: |
          context="$RUNNER_TEMP/cli-coverage-context"
          main_at() {
            gh api -X GET repos/kernel/kernel/commits -f sha=main -f until="$1" -f per_page=1 --jq '.[0].sha // empty'
          }
          file_at() {
            gh api -H 'Accept: application/vnd.github.raw' "repos/kernel/kernel/contents/$1?ref=$2"
          }
          head=$(main_at "$NEW_DATE")
          test -n "$head"
          for file in openapi.yaml stainless.yaml; do
            file_at "packages/api/$file" "$head" > "$context/api/$file"
          done
          base=""
          if [[ -n "$OLD_DATE" ]]; then
            base=$(main_at "$OLD_DATE")
          fi
          if [[ -n "$base" ]]; then
            file_at packages/api/openapi.yaml "$base" > "$RUNNER_TEMP/openapi-base.yaml"
            diff -u --label "openapi.yaml@$base" --label "openapi.yaml@$head" \
              "$RUNNER_TEMP/openapi-base.yaml" "$context/api/openapi.yaml" \
              > "$context/openapi-diff.patch" || [[ $? -eq 1 ]]
            rm "$RUNNER_TEMP/openapi-base.yaml"
          else
            printf 'Spec baseline unavailable; compare all relevant descriptions in openapi.yaml.\n' > "$context/openapi-diff.patch"
          fi
          gh api --method DELETE /installation/token

      - name: Encrypt CLI coverage context
        run: |
          # This repository is public and its artifacts are downloadable, but the
          # spec comes from a private repository, so only ciphertext is uploaded.
          cert=updater/.github/keys/cli-coverage-context.crt
          if [[ ! -s "$cert" ]]; then
            echo "::error::Missing $cert. Create the context key pair and the CLI_COVERAGE_CONTEXT_KEY secret first."
            exit 1
          fi
          tar -C "$RUNNER_TEMP/cli-coverage-context" -czf "$RUNNER_TEMP/cli-coverage-context.tar.gz" .
          openssl cms -encrypt -binary -aes-256-gcm -recip "$cert" -keyopt rsa_padding_mode:oaep \
            -outform DER -in "$RUNNER_TEMP/cli-coverage-context.tar.gz" -out "$RUNNER_TEMP/cli-coverage-context.cms"
          rm -rf "$RUNNER_TEMP/cli-coverage-context" "$RUNNER_TEMP/cli-coverage-context.tar.gz"

      - name: Upload CLI coverage context
        id: upload-context
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: cli-coverage-context
          path: ${{ runner.temp }}/cli-coverage-context.cms
          if-no-files-found: error
          retention-days: 1
          # A failed generate keeps the context for retries, and "Re-run all
          # jobs" uploads it again under the same name.
          overwrite: true

  generate:
    needs: prefetch
    if: github.repository == 'kernel/kernel-go-sdk'
    runs-on: ubuntu-latest
    timeout-minutes: 55
    permissions:
      contents: read
      # The model credentials step exchanges the job's OIDC token for short-lived model credentials.
      id-token: write
    outputs:
      changed: ${{ steps.snapshot.outputs.changed }}
      main_sha: ${{ steps.cli-clone.outputs.main_sha }}
      update_sha: ${{ steps.cli-clone.outputs.update_sha }}
      rebased: ${{ steps.cli-clone.outputs.rebased }}
      agent_base_tree: ${{ steps.cli-clone.outputs.agent_base_tree }}
    steps:
      - name: Checkout SDK repo
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false
          ref: ${{ needs.prefetch.outputs.sha }}

      - name: Checkout updater scripts
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          path: updater
          sparse-checkout: .github/scripts
          persist-credentials: false

      - name: Download CLI coverage context
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: cli-coverage-context
          path: ${{ runner.temp }}/encrypted-context

      - name: Decrypt CLI coverage context
        env:
          CONTEXT_KEY: ${{ secrets.CLI_COVERAGE_CONTEXT_KEY }}
        run: |
          : "${CONTEXT_KEY:?Set the CLI_COVERAGE_CONTEXT_KEY repository secret}"
          umask 077
          key="$RUNNER_TEMP/cli-coverage-context-key.pem"
          base64 -d <<< "$CONTEXT_KEY" > "$key"
          openssl cms -decrypt -binary -inform DER -inkey "$key" \
            -in "$RUNNER_TEMP/encrypted-context/cli-coverage-context.cms" -out "$RUNNER_TEMP/cli-coverage-context.tar.gz"
          rm "$key"
          mkdir -p /tmp/cli-coverage-context
          tar -C /tmp/cli-coverage-context -xzf "$RUNNER_TEMP/cli-coverage-context.tar.gz"
          rm -r "$RUNNER_TEMP/cli-coverage-context.tar.gz" "$RUNNER_TEMP/encrypted-context"

      - name: Setup Node
        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
        with:
          node-version: '22'

      - name: Install Pi
        env:
          PI_TELEMETRY: '0'
        run: |
          npm install -g --ignore-scripts @earendil-works/pi-coding-agent
          pi --version

      - name: Configure git identity
        run: |
          git config --global user.name "kernel-internal[bot]"
          git config --global user.email "260533166+kernel-internal[bot]@users.noreply.github.com"

      - name: Setup Go
        uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16 # v6
        with:
          go-version: 'stable'
          # Pi can write to the Go caches, so they must never be saved for other runs.
          cache: false

      - name: Clone CLI repo
        id: cli-clone
        run: |
          git clone https://github.com/kernel/cli.git /tmp/kernel-cli
          cd /tmp/kernel-cli
          git config user.name "kernel-internal[bot]"
          git config user.email "260533166+kernel-internal[bot]@users.noreply.github.com"
          echo "main_sha=$(git rev-parse origin/main)" >> "$GITHUB_OUTPUT"
          if git show-ref --verify --quiet refs/remotes/origin/cli-coverage-update; then
            echo "update_sha=$(git rev-parse origin/cli-coverage-update)" >> "$GITHUB_OUTPUT"
            git switch --track origin/cli-coverage-update
            if ! git rebase origin/main; then
              git rebase --abort
              # The agent covers everything since main's SDK version, so a bot-only
              # branch can be regenerated from main. Human commits must be kept.
              if git log --no-merges --format=%ae origin/main..origin/cli-coverage-update \
                | grep -qvxF '260533166+kernel-internal[bot]@users.noreply.github.com'; then
                echo "::error::cli-coverage-update has human commits that conflict with main. Resolve the conflicts on that branch, then rerun this workflow."
                exit 1
              fi
              echo "::warning::cli-coverage-update conflicts with main; regenerating it from main."
              git switch -C cli-coverage-update origin/main
            else
              echo "rebased=true" >> "$GITHUB_OUTPUT"
            fi
          else
            git switch -c cli-coverage-update origin/main
          fi
          # The agent's changes are published on top of this head, so human
          # commits on the update branch keep their content and authorship.
          echo "agent_base=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
          echo "agent_base_tree=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_OUTPUT"

      - name: Model credentials
        uses: kernel/security-workflows/.github/actions/llm-credentials@4144994f1d6977e07ef5a5832599ee4faaae9550 # main
        with:
          model: ${{ vars.PI_PREFERRED_MODEL }}
          anthropic-federation-rule-id: ${{ vars.ANTHROPIC_FEDERATION_RULE_ID }}
          anthropic-organization-id: ${{ vars.ANTHROPIC_ORGANIZATION_ID }}
          anthropic-service-account-id: ${{ vars.ANTHROPIC_SERVICE_ACCOUNT_ID }}
          openai-identity-provider-id: ${{ vars.OPENAI_IDENTITY_PROVIDER_ID }}
          openai-service-account-id: ${{ vars.OPENAI_SERVICE_ACCOUNT_ID }}
          openai-audience: ${{ vars.OPENAI_WIF_AUDIENCE }}

      - name: Update CLI coverage
        env:
          PI_PREFERRED_MODEL: ${{ vars.PI_PREFERRED_MODEL }}
          PI_SKIP_VERSION_CHECK: '1'
          PI_TELEMETRY: '0'
          KERNEL_API_KEY: ${{ secrets.KERNEL_API_KEY }}
          TRIGGER: "${{ github.event_name }} ${{ inputs.pr_number && format('(PR #{0})', inputs.pr_number) || '' }}"
          BRANCH_PREFIX: cli-coverage-update
        run: |
          : "${PI_PREFERRED_MODEL:?Set the PI_PREFERRED_MODEL organization variable}"
          mkdir -p "$RUNNER_TEMP/cli-scratch"
          pi --print --no-session --approve \
            --model "$PI_PREFERRED_MODEL" --thinking max \
            "You are a CLI updater that implements missing CLI commands based on SDK updates.

          Git is available for local diffs only. You have no GitHub publishing credentials.
          Do not commit, push, open, or merge PRs. The workflow validates and publishes your changes.

          # Context
          - SDK Repo: ${{ github.repository }} (current directory)
          - SDK Module: ${{ needs.prefetch.outputs.module }}
          - SDK Version: ${{ needs.prefetch.outputs.version }}
          - Commit SHA: ${{ needs.prefetch.outputs.sha }}
          - Commit Author: ${{ needs.prefetch.outputs.author }}
          - Trigger: $TRIGGER
          - API Spec Location: /tmp/cli-coverage-context/api (openapi.yaml and stainless.yaml as of this SDK release)
          - CLI Repo Location: /tmp/kernel-cli
          - Update Branch Prefix: cli-coverage-update

          # Background
          The Go SDK (this repo) was just updated by Stainless, and may contain new API methods. The CLI (kernel/cli) needs to be updated to expose these new methods as CLI commands.
          The CLI main branch is on SDK version ${{ needs.prefetch.outputs.old_version }}, and we are updating it to ${{ needs.prefetch.outputs.version }}.
          The update branch may already hold coverage from earlier runs for releases in between; keep it and build on it.

          # Source Files
          - SDK api.md: Current directory - READ THIS FILE FIRST. This is the authoritative list of all SDK methods and their signatures.
          - SDK *.go files: Current directory - Contains param structs (e.g., BrowserNewParams, DeploymentListParams) with all available options/fields.
          - SDK diff: /tmp/cli-coverage-context/sdk-diff.patch - IMPORTANT: This is the diff of api.md and Go source files between the SDK version on CLI main (${{ needs.prefetch.outputs.old_version }}) and the new version (${{ needs.prefetch.outputs.version }}). Read this file to see exactly what methods, params, and fields were added or changed. Any additions here MUST be reflected in the CLI.
          - API Spec: /tmp/cli-coverage-context/api/stainless.yaml - SDK configuration with resources and methods
          - API Spec: /tmp/cli-coverage-context/api/openapi.yaml - Full OpenAPI specification. CHECK for x-cli-skip: true on endpoints - skip those from CLI coverage.
          - API Spec diff: /tmp/cli-coverage-context/openapi-diff.patch - Spec changes between the SDK version on CLI main and the new one, including endpoint, parameter, and field description changes.
          - CLI: /tmp/kernel-cli - Existing CLI commands

          # Task

          ## Step 1: Update SDK Version (ALWAYS DO THIS FIRST)
          - Go to /tmp/kernel-cli
          - Update go.mod to require the latest SDK: ${{ needs.prefetch.outputs.module }}@${{ needs.prefetch.outputs.version }}
          - Run: go get ${{ needs.prefetch.outputs.module }}@${{ needs.prefetch.outputs.version }}
          - Run: go mod tidy
          - This ensures the CLI always uses the latest SDK, even if no new commands are added

          ## Step 2: Review SDK Diff (CRITICAL - DO THIS BEFORE THE FULL ENUMERATION)
          Read /tmp/cli-coverage-context/sdk-diff.patch to see exactly what changed in the SDK between the version on CLI main and the new version.
          This diff shows new methods, new param fields, and changed signatures — these are the changes most likely to need CLI coverage.
          Treat every addition in this diff as a checklist item: each new method needs a CLI command, each new param field needs a CLI flag.
          After verifying these are covered, proceed to the full enumeration below to catch anything else.

          ## Step 3: Full SDK Method Enumeration (CRITICAL - DO NOT SKIP)
          You MUST perform a complete enumeration of ALL SDK methods and their parameters. Do NOT rely only on the diff from Step 2.

          3a. Read the api.md file in the SDK repo root. This file lists EVERY SDK method in the format:
              - \`client.Resource.Method(ctx, params)\` with links to param types
              Extract a complete list of all methods.

          3b. For EACH SDK method, read the corresponding param type from the Go source files.
              For example:
              - BrowserNewParams in browser.go -> lists all fields like \`Proxy\`, \`Profile\`, \`Viewport\`, etc.
              - DeploymentNewParams in deployment.go -> lists all fields like \`AppName\`, \`Region\`, \`EnvVars\`, etc.
              Each field in a Params struct represents an option that could be a CLI flag.

          3c. Build a complete SDK coverage matrix:
              | SDK Method | SDK Param Type | SDK Param Fields |
              |------------|----------------|------------------|
              | client.Browsers.New | BrowserNewParams | Proxy, Profile, Viewport, Extensions, ... |
              | client.Browsers.List | BrowserListParams | Page, PerPage, IncludeDeleted, ... |
              | client.Deployments.New | DeploymentNewParams | AppName, Region, EnvVars, ... |
              | ... | ... | ... |

          ## Step 4: Full CLI Command Enumeration (CRITICAL - DO NOT SKIP)
          Enumerate ALL existing CLI commands and their flags.

          4a. Look at cmd/ directory structure for existing commands
          4b. For each command file, extract:
              - The command name/path (e.g., \`kernel browser create\`)
              - All flags defined for that command
          4c. Build a CLI coverage matrix:
              | CLI Command | CLI Flags |
              |-------------|-----------|
              | kernel browser create | --proxy, --profile, --viewport, ... |
              | kernel browser list | --page, --per-page, ... |
              | ... | ... |

          ## Step 5: Gap Analysis (CRITICAL - DO NOT SKIP)
          Compare the SDK matrix (Step 3) with the CLI matrix (Step 4) to identify:

          5a. Missing commands: SDK methods with NO corresponding CLI command
          5b. Missing flags: SDK param fields with NO corresponding CLI flag
          5c. Cross-check against the SDK diff from Step 2: every addition in /tmp/cli-coverage-context/sdk-diff.patch MUST appear as a gap to address (new method = missing command, new param field = missing flag) unless it already exists in the CLI.
          5d. Create a gap report:
              ## Missing Commands
              - client.Browsers.LoadExtensions -> needs \`kernel browser load-extensions\`
              - client.Proxies.Check -> needs \`kernel proxy check\`

              ## Missing Flags
              - BrowserNewParams.SomeNewField -> \`kernel browser create\` needs --some-new-field
              - DeploymentListParams.Status -> \`kernel deployment list\` needs --status

          ## Step 6: Implement Missing Coverage
          For each gap identified in Step 5:
          - Implement missing commands following existing patterns
          - Add missing flags to existing commands
          - Run \`go build ./...\` to verify the code compiles

          ## Step 6b: Sync Help Text With the API Spec
          The SDK is generated from openapi.yaml, so its endpoint, parameter, and schema descriptions are the source of truth for what the API does.
          - For every changed summary or description in /tmp/cli-coverage-context/openapi-diff.patch that belongs to an endpoint, parameter, or field the CLI exposes, update the matching command Short/Long text and flag usage string. Use the spec text for anything you add in this run too.
          - Adapt the text; do not copy it verbatim. API descriptions are written for HTTP callers and often reference other endpoints, HTTP methods, status codes, headers, or JSON body paths that mean nothing to a CLI user. Rewrite those references in CLI terms: name the kernel command and flags that do the equivalent. For example, \"List connections with \`GET /auth/connections\`\" becomes \"List connections with \`kernel auth connections list\`\", and a body field like \`max_concurrent_sessions\` becomes its flag, \`--max-concurrent-sessions\`. Drop API details that do not apply to the command.
          - Follow existing help text style: keep Short to one concise line and put caveats in Long.
          - Preserve meaning exactly: limits, defaults, units, accepted values, deprecations, and caveats must match the spec. Do not invent behavior the spec does not state.
          - Change only text whose meaning the spec change affects, or existing text the spec now shows to be wrong. Do not restyle unrelated help text.

          ## Step 7: Test Your Changes (ALWAYS DO THIS)
          After implementing, build the CLI and smoke test the new commands/flags you just added against the real API.
          The KERNEL_API_KEY environment variable is available for authentication.

          Keep every smoke-test artifact outside the checkout: write binaries, command output, JSON responses, and logs under $RUNNER_TEMP/cli-scratch, never under /tmp/kernel-cli.

          7a. Build the CLI:
              cd /tmp/kernel-cli && go build -o $RUNNER_TEMP/cli-scratch/kernel ./cmd/kernel

          7b. For each new command or flag you added:
              - Run the command against the real API and verify it succeeds
              - For create/write commands: create a resource, verify it works, then clean up (delete it)
              - For read commands: call them and verify the output format is correct
              - For flag additions: create a resource with the new flag and verify it shows up in the get output
              Example test flow for a new browser flag:
                $RUNNER_TEMP/cli-scratch/kernel browsers create --new-flag value -t 30
                $RUNNER_TEMP/cli-scratch/kernel browsers get <id>  # verify new-flag appears
                $RUNNER_TEMP/cli-scratch/kernel browsers delete <id>  # clean up

          7c. If any command fails or produces unexpected output, fix the implementation and re-test before proceeding.

          7d. If you added no new commands or flags (SDK version bump only), skip this step.

          ## Step 8: Review and Report
          - Read the full diff against ${{ steps.cli-clone.outputs.main_sha }} (CLI main as of this run) and remove unrelated changes or unnecessary wrappers/casts.
          - Write $RUNNER_TEMP/cli-coverage-report.md with the new commands/flags, help text updated to match spec changes (with the spec operation or field each follows), intentional exclusions, and test results or limitations.
          - The report replaces the PR description, so it must describe every change in the diff against ${{ steps.cli-clone.outputs.main_sha }}, including changes earlier runs left on this branch, not only this run's.
          - The report becomes part of a public PR. Include no credentials, customer information, private discussions, or internal URLs.
          - Do not fetch, commit, push, change git authentication, or open PRs. Leave the changes for the workflow to validate and publish.
          - Only go.mod, go.sum, and .go files under cmd/ and pkg/ are published. The workflow discards every other change before validation.

          # SDK Method -> CLI Command Mapping Guide
          - client.Resource.New() -> kernel resource create
          - client.Resource.List() -> kernel resource list
          - client.Resource.Get() -> kernel resource get
          - client.Resource.Delete() -> kernel resource delete
          - client.Resource.Update() -> kernel resource update
          - client.Resource.Sub.Action() -> kernel resource sub action
          - client.Resource.CustomAction() -> kernel resource custom-action

          # SDK Param Field -> CLI Flag Mapping Guide
          - CamelCaseField -> --camel-case-field
          - TimeoutSeconds -> --timeout-seconds
          - IncludeDeleted -> --include-deleted
          - Nested structs: Viewport.Width -> --viewport-width or separate flags

          # Implementation Guidelines
          - Follow the existing CLI code patterns in /tmp/kernel-cli
          - Use cobra for command definitions
          - Use the Kernel Go SDK (this repo) for API calls
          - Include proper flag definitions with descriptions matching SDK field comments
          - Add help text for commands matching SDK method comments
          - Handle errors appropriately
          - Match the style of existing commands

          # CLI Pagination UX for Paginated List Endpoints
          When an SDK update introduces pagination on a list endpoint (e.g., the return type
          changes to \`*pagination.OffsetPagination[T]\` and the params gain \`Limit\`/\`Offset\`
          fields), do NOT naively expose \`--limit\` and \`--offset\` flags. Instead, follow the
          page-based UX pattern used by \`kernel app list\` (see cmd/app.go):

          ## Flags
          - Add \`--page\` (int, default 1): 1-based page number.
          - Add \`--per-page\` (int, default 20): items per page.
          - Do NOT add \`--limit\` or \`--offset\` flags. These are implementation details the
            user should not need to think about.
          - Keep any filter flags the endpoint supports (e.g., \`--query\`, \`--name\`, \`--status\`).

          ## Pagination Logic (the \"+1 trick\")
          The SDK's \`OffsetPagination\` struct stores response headers (\`X-Has-More\`,
          \`X-Next-Offset\`) in private fields that the CLI cannot access. To detect whether
          more pages exist without an extra API call, request one extra item:
          1. Set \`params.Limit = perPage + 1\`
          2. Set \`params.Offset = (page - 1) * perPage\`
          3. If the API returns more than \`perPage\` items, \`hasMore = true\`; truncate to
             \`perPage\` items for display.
          4. Otherwise \`hasMore = false\`.

          ## Pagination Footer
          After rendering the table, always print a pagination footer (using \`pterm.Printf\`
          so test output capture works):
            Page: 1 Per-page: 20 Items this page: 20 Has more: yes
            Next: kernel <resource> list --page 2 --per-page 20
          - The footer line is always printed (even when \`hasMore\` is false).
          - The \"Next:\" line is only printed when \`hasMore\` is true.
          - Preserve all filter flags in the \"Next:\" hint. Always quote string values
            (e.g., \`--query \"value\"\`) to handle multi-word values safely.
          - Use \`lo.Ternary(hasMore, \"yes\", \"no\")\` for the Has more value
            (import \`github.com/samber/lo\`, already a dependency).
          - Do NOT print the footer when \`--output json\` is used.

          ## Input Struct
          Use \`Page int\` and \`PerPage int\` in the list input struct, not \`Limit\`/\`Offset\`.
          Default both defensively in the List method body (\`page <= 0\` -> 1, \`perPage <= 0\` -> 20).

          ## Example Reference
          See \`cmd/profiles.go\` ProfilesCmd.List and \`cmd/app.go\` runAppList for working
          implementations of this pattern.

          # Constraints
          - ALWAYS update the SDK version in go.mod - this is the primary purpose
          - ALWAYS perform the full enumeration (Steps 2-4) - this is critical for finding gaps
          - ALL SDK methods in api.md MUST have corresponding CLI commands, EXCEPT those marked with x-cli-skip in openapi.yaml
          - SKIP endpoints marked with x-cli-skip: true in openapi.yaml - these are internal endpoints (e.g., hosted UI auth flows) not suitable for CLI
          - The API spec is taken from the API's main branch at release time and can be ahead of the released SDK. The SDK defines what exists: never add commands or flags for operations or fields this SDK version does not have. Use the spec only for the meaning of things the SDK has.
          - Streaming methods may have different CLI implementations (e.g., follow flags)
          - Even if no coverage gaps are found, still leave the SDK version bump and write the coverage report
          - Ensure code compiles before finishing
          "

      - name: Stop model credentials
        if: always()
        uses: kernel/security-workflows/.github/actions/llm-credentials@4144994f1d6977e07ef5a5832599ee4faaae9550 # main
        with:
          stop: true

      - name: Snapshot publishable changes
        id: snapshot
        working-directory: /tmp/kernel-cli
        env:
          AGENT_BASE: ${{ steps.cli-clone.outputs.agent_base }}
        run: |
          git reset -q --soft "$AGENT_BASE"
          git add -A
          git diff --cached --name-only --no-renames -z \
            | bash "$GITHUB_WORKSPACE/updater/.github/scripts/cli-update-disallowed-paths.sh" > "$RUNNER_TEMP/excluded-paths"
          if [[ -s "$RUNNER_TEMP/excluded-paths" ]]; then
            echo "::warning::Discarding changes outside the CLI updater allowlist:"
            tr '\0' '\n' < "$RUNNER_TEMP/excluded-paths"
            GIT_LITERAL_PATHSPECS=1 git reset -q --pathspec-from-file="$RUNNER_TEMP/excluded-paths" --pathspec-file-nul
          fi
          git diff --cached --binary --no-renames --no-ext-diff --no-textconv > "$RUNNER_TEMP/changes.patch"
          git reset -q --hard
          git clean -fdq
          if [[ -s "$RUNNER_TEMP/changes.patch" ]]; then
            git apply --index "$RUNNER_TEMP/changes.patch"
            echo "changed=true" >> "$GITHUB_OUTPUT"
          fi

      - name: Verify CLI changes
        working-directory: /tmp/kernel-cli
        env:
          SDK_MODULE: ${{ needs.prefetch.outputs.module }}
          SDK_VERSION: ${{ needs.prefetch.outputs.version }}
        run: |
          test -s "$RUNNER_TEMP/cli-coverage-report.md"
          expected=$(go list -m -f '{{.Version}}' "$SDK_MODULE@$SDK_VERSION")
          test "$(go list -m -f '{{.Version}}' "$SDK_MODULE")" = "$expected"
          # Validation must build against published modules, not local replacements.
          test -z "$(go list -m -f '{{with .Replace}}{{.Path}}{{end}}' "$SDK_MODULE")"
          go mod edit -json | jq -e '[.Replace[]? | select(.New.Version == null)] | length == 0'
          go build ./...
          go vet ./...
          go test ./...
          git diff --cached --check

      - name: Upload validated changes
        if: steps.snapshot.outputs.changed == 'true'
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: cli-coverage-update
          path: |
            ${{ runner.temp }}/changes.patch
            ${{ runner.temp }}/cli-coverage-report.md
          if-no-files-found: error
          retention-days: 7

  publish:
    needs: [prefetch, generate]
    if: needs.generate.outputs.changed == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    env:
      SDK_VERSION: ${{ needs.prefetch.outputs.version }}
      MAIN_SHA: ${{ needs.generate.outputs.main_sha }}
      UPDATE_SHA: ${{ needs.generate.outputs.update_sha }}
      REBASED: ${{ needs.generate.outputs.rebased }}
      AGENT_BASE_TREE: ${{ needs.generate.outputs.agent_base_tree }}
    steps:
      - name: Checkout updater scripts
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          persist-credentials: false

      - name: Download validated changes
        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
        with:
          name: cli-coverage-update
          path: ${{ runner.temp }}/cli-coverage-update

      - name: Checkout CLI
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
        with:
          repository: kernel/cli
          path: cli
          fetch-depth: 0
          persist-credentials: false

      - name: Apply validated changes
        working-directory: cli
        run: |
          git config user.name "kernel-internal[bot]"
          git config user.email "260533166+kernel-internal[bot]@users.noreply.github.com"
          if [[ "$REBASED" == true ]]; then
            git switch -c cli-coverage-update "$UPDATE_SHA"
            git rebase -q "$MAIN_SHA"
          else
            git switch -c cli-coverage-update "$MAIN_SHA"
          fi
          if [[ "$(git rev-parse 'HEAD^{tree}')" != "$AGENT_BASE_TREE" ]]; then
            echo "::error::The rebuilt update branch differs from the one the changes were validated on."
            exit 1
          fi
          git apply --index "$RUNNER_TEMP/cli-coverage-update/changes.patch"
          git diff --cached --name-only --no-renames -z \
            | bash ../.github/scripts/cli-update-disallowed-paths.sh > "$RUNNER_TEMP/disallowed-paths"
          if [[ -s "$RUNNER_TEMP/disallowed-paths" ]]; then
            echo "::error::Validated changes include paths outside the CLI updater allowlist:"
            tr '\0' '\n' < "$RUNNER_TEMP/disallowed-paths"
            exit 1
          fi
          if git diff --cached --raw --no-renames | awk '$2 !~ /^(100644|100755|000000)$/ { found = 1 } END { exit !found }'; then
            echo "::error::Validated changes may only contain regular files."
            exit 1
          fi
          git commit -q -m "Update Go SDK to $SDK_VERSION and CLI coverage"

      - name: Generate CLI publishing token
        id: publish-token
        uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
        with:
          app-id: ${{ secrets.ADMIN_APP_ID }}
          private-key: ${{ secrets.ADMIN_APP_PRIVATE_KEY }}
          owner: kernel
          repositories: cli
          permission-contents: write
          permission-pull-requests: write

      - name: Open or update CLI coverage PR
        working-directory: cli
        env:
          GH_TOKEN: ${{ steps.publish-token.outputs.token }}
        run: |
          if git diff --quiet origin/main HEAD; then
            echo "CLI coverage is already up to date."
            exit 0
          fi
          gh auth setup-git
          git push --force-with-lease="cli-coverage-update:$UPDATE_SHA" origin cli-coverage-update

          body="$RUNNER_TEMP/cli-coverage-pr.md"
          {
            printf '## Summary\n\n- Update the Go SDK to `%s`.\n' "$SDK_VERSION"
            printf '\n## Coverage\n\n'
            head -c 60000 "$RUNNER_TEMP/cli-coverage-update/cli-coverage-report.md"
            printf '\n## Validation\n\n- Go build\n- Go vet\n- Go tests\n'
          } > "$body"
          pr=$(gh pr list --repo kernel/cli --head cli-coverage-update --base main \
            --state open --json number --jq '.[0].number // empty')
          title="CLI: Update Go SDK to $SDK_VERSION"
          if [[ -n "$pr" ]]; then
            gh pr edit "$pr" --repo kernel/cli --title "$title" --body-file "$body"
          else
            gh pr create --repo kernel/cli --head cli-coverage-update --base main \
              --title "$title" --body-file "$body"
          fi

  cleanup:
    needs: [prefetch, generate, publish]
    # After a failed or cancelled generate, the context stays until it expires
    # so "Re-run failed jobs" can download it again.
    if: always() && needs.generate.result == 'success' && needs.prefetch.outputs.context_artifact_id != ''
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      actions: write
    steps:
      - name: Delete CLI coverage context
        env:
          GH_TOKEN: ${{ github.token }}
          ARTIFACT_ID: ${{ needs.prefetch.outputs.context_artifact_id }}
        run: |
          if ! output=$(gh api --method DELETE "repos/$GITHUB_REPOSITORY/actions/artifacts/$ARTIFACT_ID" 2>&1); then
            # An earlier attempt of this run may already have deleted it.
            if [[ "$output" != *"HTTP 404"* ]]; then
              echo "$output" >&2
              exit 1
            fi
            echo "The CLI coverage context was already deleted."
          fi