cli

Documentation

Index

• func NewKongContext(ctx context.Context, name, buildID, version string, cli any, args []string, ...) *kong.Context
• type BaseCLI
• type BuildID
• type CommonArgs
  • func (c *CommonArgs) Validate() error
• type Context
• type Service
  • func New(id, version string) *Service
• type Version

Examples

• NewKongContext

Functions

func NewKongContext

func NewKongContext(
	ctx context.Context,
	name, buildID, version string,
	cli any,
	args []string,
	opts ...kong.Option,
) *kong.Context

NewKongContext creates a Kong context with required params.

Example

ExampleKongBindAndRun shows how to wire up a command and run it using NewKongContext. It simulates invoking the CLI as:

grade --dir . --run true

package main

import (
	"context"
	"fmt"

	"github.com/jh125486/gradebot/pkg/cli"
)

// exampleCommand demonstrates a simple Kong command that embeds CommonArgs and
// receives a bound *cli.Service in its Run method. This mirrors how course-specific
// commands should be structured when building a grader CLI.
type exampleCommand struct {
	Args cli.CommonArgs `embed:""`
}

// Run executes the command using the injected Service. In a real grader this
// is where you'd construct a client.Config from the parsed args and call
// client.ExecuteProject with the appropriate evaluators.
func (c *exampleCommand) Run(svc *cli.Service) error {
	// Print a small, deterministic value so the example can be tested and shown
	// on pkg.go.dev. Real implementations should use svc and c.Args to run the
	// grading workflow.
	fmt.Fprintf(svc.Stdout, "svc_ok: %v\n", svc.Client != nil)
	return nil
}

// ExampleKongBindAndRun shows how to wire up a command and run it using
// NewKongContext. It simulates invoking the CLI as:
//
//	grade --dir . --run true
func main() {
	var CLI struct {
		Grade exampleCommand `cmd:"" help:"Grade project"`
	}

	// Create a Kong context (binding is performed inside NewKongContext). In
	// some environments calling kctx.Run(...) can exercise Kong's runtime
	// binding paths; here we only assert the context was created successfully.
	kctx := cli.NewKongContext(context.Background(), "gradebot", "test-build-id", "v1.0.1", &CLI, []string{"grade", "--dir", ".", "--run", "true"})
	fmt.Println("kctx_created:", kctx != nil)

	// Manually construct a service and run the command to demonstrate how the
	// Run method receives an injected *cli.Service. This keeps the example
	// deterministic and safe to run in package tests.
	svc := cli.New("build-id-123", "v1.0.0")
	cmd := &exampleCommand{Args: cli.CommonArgs{WorkDir: cli.CommonArgs{}.WorkDir}} // leave defaults
	_ = cmd.Run(svc)

}

Output:
kctx_created: true
svc_ok: true

Types

type BaseCLI

type BaseCLI struct {
	Version kong.VersionFlag `help:"Show version and exit" name:"version"`
}

BaseCLI defines the core fields for all CLIs using our framework.

type BuildID

type BuildID string

BuildID is a distinct type for the hashed build identifier. Used for Kong binding to avoid conflicts with plain strings.

type CommonArgs

type CommonArgs struct {
	ServerURL string            `` /* 136-byte string literal not displayed */
	WorkDir   client.WorkDir    `` /* 167-byte string literal not displayed */
	RunCmd    string            `` /* 130-byte string literal not displayed */
	Env       map[string]string `` /* 128-byte string literal not displayed */
}

CommonArgs contains arguments shared across project grading commands.

func (*CommonArgs) Validate

func (c *CommonArgs) Validate() error

type Context

type Context struct {
	context.Context
}

Context wraps context.Context to work around reflection issues in Kong's Bind(). Use this as the parameter type for Kong command Run methods.

type Service

type Service struct {
	Client         *http.Client
	Stdin          io.Reader
	Stdout         io.Writer
	Version        string
	CommandBuilder rubrics.CommandBuilder
}

Service holds global dependencies that can be injected into commands. It separates runtime dependencies from configuration (args).

func New

func New(id, version string) *Service

New creates a new Service with default implementations. buildID is used for the Authorization header in the HTTP client.

type Version

type Version string

Version is a distinct type for the application version. Used for Kong binding to track server/client version mismatches.