From 23d4b9be60db33c3de40da6666e3c51ded15dba5 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 17 Jan 2026 20:39:07 +0000 Subject: [PATCH 1/2] fix: update CLI coverage workflow to perform full SDK method enumeration The previous prompt only checked recent commits and vaguely asked to identify coverage gaps. This update makes the prompt explicit about: 1. Reading api.md as the authoritative source of ALL SDK methods 2. Reading param structs from Go files to enumerate ALL options/fields 3. Building an SDK coverage matrix (methods + params) 4. Building a CLI coverage matrix (commands + flags) 5. Performing gap analysis to find missing commands and flags 6. Mapping guidance for SDK param fields to CLI flags (CamelCase -> kebab-case) This ensures the agent does a complete enumeration rather than just checking what changed in the most recent commit. Co-authored-by: mason --- .github/workflows/update-cli-coverage.yml | 136 +++++++++++++++------- 1 file changed, 95 insertions(+), 41 deletions(-) diff --git a/.github/workflows/update-cli-coverage.yml b/.github/workflows/update-cli-coverage.yml index 6c4603f..5d90474 100644 --- a/.github/workflows/update-cli-coverage.yml +++ b/.github/workflows/update-cli-coverage.yml @@ -89,59 +89,103 @@ jobs: 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. # Source Files - - SDK: Current directory - check for new/changed methods in the Go SDK + - 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. - API Spec: /tmp/kernel-api/packages/api/stainless.yaml - SDK configuration with resources and methods - API Spec: /tmp/kernel-api/packages/api/openapi.yaml - Full OpenAPI specification - CLI: /tmp/kernel-cli - Existing CLI commands # Task - 1. ALWAYS update the CLI to use the latest Go SDK version: - - Go to /tmp/kernel-cli - - Update go.mod to require the latest SDK: ${{ steps.sdk-version.outputs.module }}@${{ steps.sdk-version.outputs.version }} - - Run: go get ${{ steps.sdk-version.outputs.module }}@${{ steps.sdk-version.outputs.version }} - - Run: go mod tidy - - This ensures the CLI always uses the latest SDK, even if no new commands are added - 2. Check the recent commit(s) to this SDK repo to see what methods were added/changed: - git log -1 --name-only - git diff HEAD~1 --name-only - - 3. Read the stainless.yaml to understand the full resource/method structure - - 4. Check the CLI repo at /tmp/kernel-cli to see what commands already exist: - - Look at cmd/ directory structure for existing commands - - Identify which SDK methods have CLI command equivalents - - 5. Identify coverage gaps - SDK methods that don't have CLI equivalents, or new SDK method parameters that aren't exposed via the CLI - - 6. If new commands or flags are needed: - - Implement them in /tmp/kernel-cli following existing patterns - - Run \`go build ./...\` to verify the code compiles - - 7. Create and push changes (SDK version update + any new commands): - - Create/update the evergreen branch: cli-coverage-update (always use this single branch name) - - Commit with message describing SDK version bump and any new commands - - Force push changes to the CLI repo (since we're updating an evergreen branch) - - Create or update an evergreen PR in kernel/cli (check if PR already exists for this branch first) - - Tag the commit author as a reviewer - - 8. If only SDK version was updated (no new commands), still update the evergreen PR with title 'CLI: Update Go SDK to ' - - # Mapping Guide - Use these mappings to implement CLI commands: - - client.Resource.Create() -> kernel resource create + ## Step 1: Update SDK Version (ALWAYS DO THIS FIRST) + - Go to /tmp/kernel-cli + - Update go.mod to require the latest SDK: ${{ steps.sdk-version.outputs.module }}@${{ steps.sdk-version.outputs.version }} + - Run: go get ${{ steps.sdk-version.outputs.module }}@${{ steps.sdk-version.outputs.version }} + - Run: go mod tidy + - This ensures the CLI always uses the latest SDK, even if no new commands are added + + ## Step 2: 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 recent commits. + + 2a. 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. + + 2b. 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. + + 2c. 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 | Limit, Offset, IncludeDeleted, ... | + | client.Deployments.New | DeploymentNewParams | AppName, Region, EnvVars, ... | + | ... | ... | ... | + + ## Step 3: Full CLI Command Enumeration (CRITICAL - DO NOT SKIP) + Enumerate ALL existing CLI commands and their flags. + + 3a. Look at cmd/ directory structure for existing commands + 3b. For each command file, extract: + - The command name/path (e.g., \`kernel browser create\`) + - All flags defined for that command + 3c. Build a CLI coverage matrix: + | CLI Command | CLI Flags | + |-------------|-----------| + | kernel browser create | --proxy, --profile, --viewport, ... | + | kernel browser list | --limit, --offset, ... | + | ... | ... | + + ## Step 4: Gap Analysis (CRITICAL - DO NOT SKIP) + Compare the SDK matrix (Step 2) with the CLI matrix (Step 3) to identify: + + 4a. Missing commands: SDK methods with NO corresponding CLI command + 4b. Missing flags: SDK param fields with NO corresponding CLI flag + 4c. 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 5: Implement Missing Coverage + For each gap identified in Step 4: + - Implement missing commands following existing patterns + - Add missing flags to existing commands + - Run \`go build ./...\` to verify the code compiles + + ## Step 6: Commit and Push + - Create/update the evergreen branch: cli-coverage-update (always use this single branch name) + - Commit with message describing SDK version bump and any new commands/flags + - Force push changes to the CLI repo (since we're updating an evergreen branch) + - Create or update an evergreen PR in kernel/cli + + # 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 - - Add help text for commands + - 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 @@ -161,13 +205,19 @@ jobs: ## SDK Update - Updated kernel-go-sdk to ${{ steps.sdk-version.outputs.version }} - ## New Commands/Flags + ## Coverage Analysis + This PR was generated by performing a full enumeration of SDK methods and CLI commands. + + ## New Commands - \`kernel \` for \`client.Resource.Action()\` + ## New Flags + - \`--flag-name\` for \`ResourceParams.FieldName\` + Triggered by: kernel/kernel-go-sdk@${{ github.sha }} Reviewer: @' - If only SDK version update (no new commands): + If only SDK version update (no coverage gaps found): Title: 'CLI: Update Go SDK to ${{ steps.sdk-version.outputs.version }}' Body: 'This PR updates the Go SDK dependency to the latest version. @@ -175,14 +225,18 @@ jobs: ## SDK Update - Updated kernel-go-sdk to ${{ steps.sdk-version.outputs.version }} + ## Coverage Analysis + A full enumeration of SDK methods and CLI commands was performed. No coverage gaps were found. + Triggered by: kernel/kernel-go-sdk@${{ github.sha }} Reviewer: @' # Constraints - ALWAYS update the SDK version in go.mod - this is the primary purpose - - Only implement genuinely missing CLI functionality for new commands + - ALWAYS perform the full enumeration (Steps 2-4) - this is critical for finding gaps + - Only implement genuinely missing CLI functionality - Internal/admin methods may not need CLI commands - Streaming methods may have different CLI implementations - - Even if no new commands are needed, still create a PR for the SDK version bump + - Even if no coverage gaps are found, still create a PR for the SDK version bump - Ensure code compiles before pushing " --model opus-4.5 --force --output-format=text From b3020eac3fb81e628345bffcab03e45e8556ebc1 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 17 Jan 2026 20:41:05 +0000 Subject: [PATCH 2/2] feat: add manual dispatch trigger with optional PR number input The workflow can now be triggered manually via workflow_dispatch with: - An optional pr_number input to specify a specific PR - If pr_number is not provided, uses the most recent merged PR - Falls back to HEAD if no PR is found This allows re-running the CLI coverage analysis for past PRs or triggering it manually without requiring a new push to main. Co-authored-by: mason --- .github/workflows/update-cli-coverage.yml | 65 ++++++++++++++++++++--- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/.github/workflows/update-cli-coverage.yml b/.github/workflows/update-cli-coverage.yml index 5d90474..50b4c17 100644 --- a/.github/workflows/update-cli-coverage.yml +++ b/.github/workflows/update-cli-coverage.yml @@ -3,6 +3,12 @@ name: Update CLI Coverage on: push: branches: [main] + workflow_dispatch: + inputs: + pr_number: + description: 'PR number to use for context (leave empty to use most recent merged PR)' + required: false + type: string # Or trigger on releases: # release: # types: [published] @@ -14,11 +20,49 @@ jobs: update-cli-coverage: runs-on: ubuntu-latest steps: + - name: Get PR info for manual dispatch + id: pr-info + if: github.event_name == 'workflow_dispatch' + env: + GH_TOKEN: ${{ secrets.GH_TOKEN }} + run: | + if [ -n "${{ inputs.pr_number }}" ]; then + # Use provided PR number + PR_NUMBER="${{ inputs.pr_number }}" + 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@v4 with: fetch-depth: 2 fetch-tags: true + # For manual dispatch with a specific PR, checkout the merge commit + ref: ${{ steps.pr-info.outputs.merge_sha || github.sha }} - name: Install Cursor CLI run: | @@ -56,14 +100,22 @@ jobs: echo "version=$LATEST_TAG" >> $GITHUB_OUTPUT echo "SDK version: $LATEST_TAG" else - echo "version=${{ github.sha }}" >> $GITHUB_OUTPUT - echo "SDK version: ${{ github.sha }} (no tag)" + 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: Update CLI coverage env: @@ -79,8 +131,9 @@ jobs: - SDK Repo: ${{ github.repository }} (current directory) - SDK Module: ${{ steps.sdk-version.outputs.module }} - SDK Version: ${{ steps.sdk-version.outputs.version }} - - Commit SHA: ${{ github.sha }} - - Commit Author: ${{ github.event.head_commit.author.username || github.actor }} + - Commit SHA: ${{ steps.pr-info.outputs.merge_sha || github.sha }} + - Commit Author: ${{ steps.sdk-version.outputs.author }} + - Trigger: ${{ github.event_name }} ${{ inputs.pr_number && format('(PR #{0})', inputs.pr_number) || '' }} - API Repo Location: /tmp/kernel-api - CLI Repo Location: /tmp/kernel-cli - Update Branch Prefix: cli-coverage-update @@ -214,7 +267,7 @@ jobs: ## New Flags - \`--flag-name\` for \`ResourceParams.FieldName\` - Triggered by: kernel/kernel-go-sdk@${{ github.sha }} + Triggered by: kernel/kernel-go-sdk@${{ steps.pr-info.outputs.merge_sha || github.sha }} Reviewer: @' If only SDK version update (no coverage gaps found): @@ -228,7 +281,7 @@ jobs: ## Coverage Analysis A full enumeration of SDK methods and CLI commands was performed. No coverage gaps were found. - Triggered by: kernel/kernel-go-sdk@${{ github.sha }} + Triggered by: kernel/kernel-go-sdk@${{ steps.pr-info.outputs.merge_sha || github.sha }} Reviewer: @' # Constraints