diff --git a/.github/workflows/update-cli-coverage.yml b/.github/workflows/update-cli-coverage.yml new file mode 100644 index 0000000..1ced9fe --- /dev/null +++ b/.github/workflows/update-cli-coverage.yml @@ -0,0 +1,368 @@ +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 + +# Only run one instance at a time; cancel older runs when a new push arrives +concurrency: + group: update-cli-coverage + cancel-in-progress: true + +permissions: + contents: read + +jobs: + update-cli-coverage: + runs-on: ubuntu-latest + steps: + - name: Generate app token + id: app-token + uses: actions/create-github-app-token@v1 + with: + app-id: ${{ secrets.ADMIN_APP_ID }} + private-key: ${{ secrets.ADMIN_APP_PRIVATE_KEY }} + owner: kernel + + - name: Get PR info for manual dispatch + id: pr-info + if: github.event_name == 'workflow_dispatch' + env: + GH_TOKEN: ${{ steps.app-token.outputs.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: | + curl https://cursor.com/install -fsS | bash + echo "$HOME/.cursor/bin" >> $GITHUB_PATH + + - 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@v6 + with: + go-version: 'stable' + + - name: Clone API repo + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + gh repo clone kernel/hypeman /tmp/hypeman -- --depth=1 + + - name: Clone CLI repo and checkout existing branch + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + run: | + gh repo clone kernel/hypeman-cli /tmp/hypeman-cli + cd /tmp/hypeman-cli + + # Try to fetch the cli-coverage-update branch from remote + if git fetch origin cli-coverage-update 2>/dev/null; then + echo "Branch cli-coverage-update exists, checking it out..." + git checkout cli-coverage-update + # Merge latest main to keep it up to date + git merge origin/main -m "Merge main into cli-coverage-update" --no-edit || true + else + echo "Branch cli-coverage-update does not exist, creating from main..." + git checkout -b cli-coverage-update + fi + + - name: Get SDK version info + id: sdk-version + run: | + # Get the latest tag if available, otherwise use commit SHA + LATEST_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: Update CLI coverage + env: + CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} + GH_TOKEN: ${{ steps.app-token.outputs.token }} + BRANCH_PREFIX: cli-coverage-update + run: | + cursor-agent -p "You are a CLI updater that implements missing CLI commands based on SDK updates. + + The GitHub CLI is available as \`gh\` and authenticated via GH_TOKEN. Git is available. You have write access to the CLI repository (kernel/hypeman-cli). + + # Context + - SDK Repo: ${{ github.repository }} (current directory) + - SDK Module: ${{ steps.sdk-version.outputs.module }} + - SDK Version: ${{ steps.sdk-version.outputs.version }} + - 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/hypeman + - CLI Repo Location: /tmp/hypeman-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/hypeman-cli) needs to be updated to expose these new methods as CLI commands. + + # 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., InstanceNewParams, ImageNewParams) with all available options/fields. + - API Spec: /tmp/hypeman/stainless.yaml - SDK configuration with resources and methods + - API Spec: /tmp/hypeman/openapi.yaml - Full OpenAPI specification. CHECK for x-cli-skip: true on endpoints - skip those from CLI coverage. + - CLI: /tmp/hypeman-cli - Existing CLI commands (in pkg/cmd/ directory) + + # CLI Architecture + The CLI uses urfave/cli/v3 (NOT cobra). Commands are defined in /tmp/hypeman-cli/pkg/cmd/: + - Root command: pkg/cmd/cmd.go + - Resource commands: pkg/cmd/{resource}cmd.go (e.g., imagecmd.go, volumecmd.go, devicecmd.go, ingresscmd.go) + - Top-level commands: pkg/cmd/{command}.go (e.g., run.go, ps.go, rm.go, logs.go, exec.go, cp.go) + - Lifecycle commands: pkg/cmd/lifecycle.go (stop, start, standby, restore) + - Build commands: pkg/cmd/build.go + - Utilities: pkg/cmd/cmdutil.go, pkg/cmd/format.go + - Entry point: cmd/hypeman/main.go + + # Task + + ## Step 1: Update SDK Version (ALWAYS DO THIS FIRST) + - Go to /tmp/hypeman-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: + - InstanceNewParams in instance.go -> lists all fields like \`Image\`, \`Region\`, \`VolumeMounts\`, etc. + - ImageNewParams in image.go -> lists all fields like \`Name\`, \`Tag\`, etc. + - VolumeNewParams in volume.go -> lists all fields like \`Name\`, \`Size\`, 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.Instances.New | InstanceNewParams | Image, Region, VolumeMounts, ... | + | client.Instances.List | (none) | | + | client.Images.New | ImageNewParams | Name, Tag, ... | + | client.Volumes.New | VolumeNewParams | Name, Size, ... | + | ... | ... | ... | + + ## Step 3: Full CLI Command Enumeration (CRITICAL - DO NOT SKIP) + Enumerate ALL existing CLI commands and their flags. + + 3a. Look at pkg/cmd/ directory for existing command files + 3b. For each command file, extract: + - The command name/path (e.g., \`hypeman run\`, \`hypeman image list\`) + - All flags defined for that command + 3c. Build a CLI coverage matrix: + | CLI Command | CLI Flags | + |-------------|-----------| + | hypeman run | --name, --image, --quiet, ... | + | hypeman ps | --quiet, --format, ... | + | hypeman image list | --format, ... | + | hypeman volume create | --name, ... | + | ... | ... | + + ## 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.SomeResource.SomeMethod -> needs new CLI command + + ## Missing Flags + - InstanceNewParams.SomeNewField -> \`hypeman run\` needs --some-new-field + - VolumeNewParams.Region -> \`hypeman volume create\` needs --region + + ## Step 5: Implement Missing Coverage + For each gap identified in Step 4: + - Implement missing commands following existing patterns in pkg/cmd/ + - Add missing flags to existing commands + - Use urfave/cli/v3 for command and flag definitions (NOT cobra) + - Run \`go build ./...\` to verify the code compiles + + ## Step 6: Commit and Push + - You should already be on the cli-coverage-update branch (it was checked out during setup if it existed) + - If you're on main, create/switch to the cli-coverage-update branch + - Commit with message describing SDK version bump and any new commands/flags + - IMPORTANT: Do NOT force push! Use regular \`git push origin cli-coverage-update\` to preserve existing work on the branch + - If push fails due to divergence, pull and rebase first: \`git pull --rebase origin cli-coverage-update\` + - Create or update the PR in kernel/hypeman-cli + + # SDK Method -> CLI Command Mapping Guide + Instance operations use Docker-style top-level commands: + - client.Instances.New() -> hypeman run + - client.Instances.List() -> hypeman ps + - client.Instances.Delete() -> hypeman rm + - client.Instances.Get() -> (used internally by other commands) + - client.Instances.Logs() -> hypeman logs + - client.Instances.Stop() -> hypeman stop + - client.Instances.Start() -> hypeman start + - client.Instances.Standby() -> hypeman standby + - client.Instances.Restore() -> hypeman restore + - client.Instances.Stat() -> (used internally by cp) + + Resource group commands use subcommands: + - client.Images.New() -> hypeman image create + - client.Images.List() -> hypeman image list + - client.Images.Get() -> hypeman image get + - client.Images.Delete() -> hypeman image delete + - client.Volumes.New() -> hypeman volume create + - client.Volumes.List() -> hypeman volume list + - client.Volumes.Get() -> hypeman volume get + - client.Volumes.Delete() -> hypeman volume delete + - client.Volumes.NewFromArchive() -> (used internally by push) + - client.Instances.Volumes.Attach() -> hypeman volume attach + - client.Instances.Volumes.Detach() -> hypeman volume detach + - client.Devices.New() -> hypeman device register + - client.Devices.List() -> hypeman device list + - client.Devices.Get() -> hypeman device get + - client.Devices.Delete() -> hypeman device delete + - client.Devices.ListAvailable() -> hypeman device available + - client.Ingresses.New() -> hypeman ingress create + - client.Ingresses.List() -> hypeman ingress list + - client.Ingresses.Get() -> hypeman ingress get + - client.Ingresses.Delete() -> hypeman ingress delete + - client.Builds.New() -> hypeman build create (or used internally) + - client.Builds.List() -> hypeman build list + - client.Builds.Get() -> hypeman build get + - client.Builds.Cancel() -> hypeman build cancel + - client.Builds.Events() -> (used internally for streaming build output) + - client.Resources.Get() -> hypeman resources + - client.Health.Check() -> (internal, no CLI needed) + + # SDK Param Field -> CLI Flag Mapping Guide + - CamelCaseField -> --camel-case-field + - TimeoutSeconds -> --timeout-seconds + - IncludeDeleted -> --include-deleted + - Optional fields use hypeman.Opt() wrapper in SDK calls + + # Implementation Guidelines + - Follow the existing CLI code patterns in /tmp/hypeman-cli/pkg/cmd/ + - Use urfave/cli/v3 for command definitions (cli.Command struct with Flags, Action, etc.) + - Use the Hypeman Go SDK (this repo) for API calls: hypeman.NewClient(getDefaultRequestOptions(cmd)...) + - Use existing helpers: ShowJSON() for output, ResolveInstance() for name resolution, FormatTimeAgo() for timestamps + - 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 + + # Output Format + After pushing changes, create or update an evergreen PR using gh: + + 1. Check if a PR already exists for the cli-coverage-update branch: + gh pr list --repo kernel/hypeman-cli --head cli-coverage-update --json number + + 2. If PR exists, update it. If not, create a new one. + + If new commands or flags were added: + Title: 'CLI: Update hypeman SDK to and add new commands/flags' + Body: + 'This PR updates the Hypeman Go SDK to ${{ steps.sdk-version.outputs.version }} and adds CLI commands/flags for new SDK methods. + + ## SDK Update + - Updated hypeman-go to ${{ steps.sdk-version.outputs.version }} + + ## Coverage Analysis + This PR was generated by performing a full enumeration of SDK methods and CLI commands. + + ## New Commands + - \`hypeman \` for \`client.Resource.Action()\` + + ## New Flags + - \`--flag-name\` on \`hypeman \` for \`ResourceParams.FieldName\` + + Triggered by: kernel/hypeman-go@${{ steps.pr-info.outputs.merge_sha || github.sha }} + Reviewer: @' + + If only SDK version update (no coverage gaps found): + Title: 'CLI: Update Hypeman Go SDK to ${{ steps.sdk-version.outputs.version }}' + Body: + 'This PR updates the Hypeman Go SDK dependency to the latest version. + + ## SDK Update + - Updated hypeman-go 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/hypeman-go@${{ steps.pr-info.outputs.merge_sha || github.sha }} + Reviewer: @' + + # 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 or noted as internal-only in the mapping guide above + - SKIP endpoints marked with x-cli-skip: true in openapi.yaml - these are internal endpoints not suitable for CLI + - Streaming methods may have different CLI implementations (e.g., build events are streamed internally) + - Even if no coverage gaps are found, still create a PR for the SDK version bump + - Ensure code compiles before pushing + " --model opus-4.6 --force --output-format=text