Skip to content

codespace

import "github.com/linuskendall/cosmonaut/internal/codespace"

Package codespace wraps the GitHub CLI (gh) to list, create, delete, and SSH into GitHub Codespaces. All GitHub API interactions go through the GHRunner interface so they can be stubbed in tests.

Index

func BuildCreateArgs

func BuildCreateArgs(target config.Target) []string

BuildCreateArgs builds the gh codespace create command arguments.

func DeleteCodespace

func DeleteCodespace(runner GHRunner, name string) error

DeleteCodespace deletes a codespace by name.

func DescribeCodespace

func DescribeCodespace(cs *Codespace, recommended bool) string

DescribeCodespace returns a human-readable description.

func EnsureGHAuth

func EnsureGHAuth(runner GHRunner) error

EnsureGHAuth verifies the user is authenticated with gh.

func EnsureReachable

func EnsureReachable(runner GHRunner, codespaceName string) error

EnsureReachable verifies the codespace SSH server is accessible. It retries with exponential backoff since the codespace may be starting up or the SSH tunnel may be slow to establish.

func GetSSHConfig

func GetSSHConfig(runner GHRunner, codespaceName string) (string, error)

GetSSHConfig retrieves the OpenSSH config for a codespace. Retries once on failure since the SSH tunnel may not be ready immediately after EnsureReachable succeeds.

func ListAllRepos

func ListAllRepos(runner GHRunner) ([]string, error)

ListAllRepos returns all repositories the user has access to.

func MatchesTarget

func MatchesTarget(cs *Codespace, t *config.Target) bool

MatchesTarget checks whether a codespace matches a config target.

func RequireCommand

func RequireCommand(name string) error

RequireCommand checks that a command is on PATH.

func UniqueRepos

func UniqueRepos(codespaces []Codespace) []string

UniqueRepos extracts sorted unique repository names from codespaces.

type Codespace

type Codespace struct {
    Name        string     `json:"name"`
    DisplayName string     `json:"displayName,omitempty"`
    Repository  RepoField  `json:"repository"`
    State       string     `json:"state,omitempty"`
    GitStatus   *GitStatus `json:"gitStatus,omitempty"`
    MachineName string     `json:"machineName,omitempty"`
    CreatedAt   string     `json:"createdAt,omitempty"`
    LastUsedAt  string     `json:"lastUsedAt,omitempty"`
}

func ChooseCodespace

func ChooseCodespace(codespaces []Codespace, t *config.Target) (*Codespace, error)

ChooseCodespace auto-selects a codespace in non-interactive mode. Returns nil if no match, errors if ambiguous.

func CreateCodespace

func CreateCodespace(runner GHRunner, target config.Target) (*Codespace, error)

CreateCodespace creates a new codespace by POSTing directly to the GitHub REST API (`POST /repos/{owner}/{repo}/codespaces`). This bypasses the interactive prompts that `gh codespace create` emits when billing is paid by a third party or when a machine type isn't specified: prompts that fail without a terminal (e.g. from the tray/daemon). Use CreateCodespaceInteractive when running from a real TTY and prompts are desired.

func CreateCodespaceInteractive

func CreateCodespaceInteractive(runner GHRunner, target config.Target) (*Codespace, error)

CreateCodespaceInteractive creates a codespace with terminal access so gh can prompt the user if needed (e.g. machine type selection). Output is shown on the terminal in real time.

func FilterByRepo

func FilterByRepo(codespaces []Codespace, repo string) []Codespace

FilterByRepo returns codespaces belonging to a given repository.

func FindMatching

func FindMatching(codespaces []Codespace, t *config.Target) []Codespace

FindMatching returns all codespaces matching the target.

func ListAllCodespaces

func ListAllCodespaces(runner GHRunner) ([]Codespace, error)

ListAllCodespaces returns all codespaces across all repos.

func ListCodespaces

func ListCodespaces(runner GHRunner, repository string) ([]Codespace, error)

ListCodespaces returns all codespaces for a given repository.

type DefaultGHRunner

DefaultGHRunner executes real gh commands.

type DefaultGHRunner struct{}

func (DefaultGHRunner) Run

func (d DefaultGHRunner) Run(args []string) (string, error)

func (DefaultGHRunner) RunInteractive

func (d DefaultGHRunner) RunInteractive(args []string) (string, error)

func (DefaultGHRunner) RunMerged

func (d DefaultGHRunner) RunMerged(args []string) (string, error)

func (DefaultGHRunner) RunWithInput

func (d DefaultGHRunner) RunWithInput(args []string, input string) (string, error)

type GHRunner

GHRunner abstracts the GitHub CLI for testability.

type GHRunner interface {
    Run(args []string) (string, error)
    RunMerged(args []string) (string, error)
    // RunInteractive runs a command with stdin connected and output teed to
    // both a capture buffer and the real terminal. Use this when the gh
    // subprocess may need to prompt the user (e.g. machine-type selection).
    RunInteractive(args []string) (string, error)
    // RunWithInput runs a command and feeds a string to its stdin. Used for
    // `gh api --input -` calls where we pipe a JSON body.
    RunWithInput(args []string, input string) (string, error)
}

type GitStatus

type GitStatus struct {
    Ref    string `json:"ref,omitempty"`
    Branch string `json:"branch,omitempty"`
}

type RepoField

RepoField handles the gh CLI returning repository as either a string or an object.

type RepoField string

func (*RepoField) UnmarshalJSON

func (r *RepoField) UnmarshalJSON(data []byte) error

Generated by gomarkdoc