INF-1307 rewrite UX to kubectl-style verb tree

Replaced the per-API command tree (twoctl checkout/billing-account/...) with
a kubectl-style verb tree (twoctl get/create/delete/edit <resource>). Every
operation is classified by verb based on its operationId prefix (or HTTP
method fall-back) and registered under the matching verb. The resource name
falls out of the rest of the operationId, with python <locals> noise, HTTP
method suffixes, and _handler decorations stripped.

Top-level commands now mirror kubectl:

  twoctl get <resource>         twoctl explain <verb> <resource>
  twoctl create <resource>      twoctl api-resources
  twoctl delete <resource>      twoctl config set-context|use-context|
  twoctl edit <resource>                       get-contexts|current-context|
  twoctl version                               delete-context

The --context flag is a kubectl-style alias of --env. No legacy aliases
retained - this is a UX rewrite, not an addition.

Author: brtkwr

Makefile

@@ -0,0 +1,40 @@
+.PHONY: build install regen test test-cover lint tidy clean release-dry help
+
+BINARY  := twoctl
+PKG     := github.com/two-inc/twoctl-cli
+VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+LDFLAGS := -X $(PKG)/internal/httpx.Version=$(VERSION) -s -w
+
+help: ## Show this help.
+	@awk 'BEGIN {FS = ":.*##"; printf "Usage: make <target>\n\nTargets:\n"} /^[a-zA-Z_-]+:.*##/ { printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
+
+build: ## Build the twoctl binary into ./twoctl.
+	go build -ldflags "$(LDFLAGS)" -o $(BINARY) ./cmd/twoctl
+
+install: ## Install twoctl into $$GOBIN (or $$GOPATH/bin).
+	go install -ldflags "$(LDFLAGS)" ./cmd/twoctl
+
+regen: ## Refresh embedded OpenAPI specs from openapi/<api>-api.yaml.
+	./scripts/codegen.sh
+
+test: ## Run all unit tests.
+	go test ./...
+
+test-cover: ## Run tests with coverage and print per-package + total.
+	go test -coverprofile=coverage.out -covermode=atomic ./...
+	go tool cover -func=coverage.out | tail -1
+	@echo "html report: open coverage.html"
+	go tool cover -html=coverage.out -o coverage.html
+
+lint: ## Run the same lints that goreportcard.com runs.
+	./scripts/lint.sh
+
+tidy: ## Tidy go.mod / go.sum.
+	go mod tidy
+
+release-dry: ## Dry-run a goreleaser build for the current OS.
+	goreleaser build --snapshot --clean --single-target
+
+clean: ## Remove build artefacts.
+	rm -f $(BINARY) coverage.out coverage.html
+	rm -rf dist/ .build/

README.md

@@ -86,39 +86,74 @@ After installing, open a new shell. Tab-completion works on subcommands,
 flags, and any flag value that has a known enum in the OpenAPI spec
 (country codes, currencies, statuses).
 
-## Authenticate
+## Contexts
 
-`twoctl` reads your API key from (in order):
+`twoctl` uses named contexts (kubectl-style). Each context bundles a base URL
+and an OS-keychain entry holding the API key, so you can switch between
+sandbox, prod, staging, cyber, perf, release, or any custom environment
+without copy-pasting keys.
 
-1. `--api-key` flag
-2. `TWO_API_KEY` env var
-3. `~/.config/two/config.yaml`
+```sh
+twoctl ctx set sandbox --url https://api.sandbox.two.inc --key secret_test_...
+twoctl ctx set prod    --url https://api.two.inc        --key secret_prod_...
+twoctl ctx list                  # show all contexts, * marks current
+twoctl ctx use prod              # switch the default
+twoctl ctx current               # print the current name
+twoctl ctx delete temp           # remove + clear keychain entry
+```
+
+Per-invocation overrides (no switching):
 
 ```sh
-twoctl auth login                # prompts for an API key
-twoctl auth whoami               # verify the key works
+twoctl --env prod company company-search --country NO --q two
+twoctl --context cyber checkout get-order --order-id abc   # kubectl-style alias
+twoctl --url http://localhost:8080 --api-key secret_test_x ...
 ```
 
-API keys are obtained from the [Two merchant portal](https://portal.two.inc).
-Sandbox keys are prefixed `secret_test_`; production keys `secret_prod_`. `twoctl`
-infers the environment from the prefix; override with `--env sandbox|prod`.
+For built-in env names (`prod`, `sandbox`, `staging`, `cyber`, `perf`,
+`release`) twoctl knows the URL. For any other name it falls back to
+`https://api.<name>.two.inc`; override with `--url`.
+
+API key resolution order (highest precedence first):
+
+1. `--api-key` flag
+2. `TWO_API_KEY` env var
+3. OS keychain entry for the active context
+
+Keys are obtained from the [Two merchant portal](https://portal.two.inc).
 
 ## Usage
 
-The command tree mirrors the API surface:
+The command tree is kubectl-style. Every operation across every Two API
+classifies into one of `get`, `create`, `delete`, `edit` based on its
+operationId, then registers as `twoctl <verb> <resource>`:
 
+```sh
+twoctl get order --order-id abc-123        # GET /v1/order/{order_id}
+twoctl create order --file order.json      # POST /v1/order
+twoctl delete order --order-id abc-123     # POST /v1/order/{id}/cancel
+twoctl edit order --order-id abc-123 --file patch.json
+twoctl get company --q "two" --country NO  # company search
+twoctl get billing-accounts                # list
+twoctl explain create order                # JSON schema for the operation
+twoctl api-resources --verb get            # full catalog of get verbs
 ```
-twoctl checkout order-create --file order.json
-twoctl checkout order-get <order-id>
-twoctl billing-account list
-twoctl repay payment-create ...
-twoctl recourse ...
-twoctl company search --org-no 123456789 --country NO
-twoctl limits buyer-get <buyer-id>
-```
 
-Every subcommand supports `--help` listing flags derived from the OpenAPI
-operation. Request bodies can be passed via `--file path.json` or `--data '{...}'`.
+Run `twoctl get` / `twoctl create` etc. on its own to see every resource
+under that verb. Each leaf command's `--help` lists flags derived from the
+OpenAPI operation; request bodies go via `--file path.json` or `--data
+'{...}'`.
+
+Top-level commands mirror kubectl:
+
+| `twoctl` | `kubectl` analogue |
+| --- | --- |
+| `get` / `create` / `delete` / `edit` | the same verbs |
+| `explain <verb> <resource>` | `explain` |
+| `api-resources` | `api-resources` |
+| `config set-context / use-context / get-contexts / current-context / delete-context` | the same |
+| `version` | `version` |
+| `--context` / `--env` (alias) | `--context` |
 
 ## Agent-friendly features
 
@@ -165,14 +200,20 @@ twoctl upgrade --enable-autocheck   # turn it back on
 
 ## APIs covered
 
-| API | Subcommand | Spec |
-| --- | --- | --- |
-| Checkout (Order) | `twoctl checkout` | [checkout-api.yaml](openapi/checkout-api.yaml) |
-| Billing Account | `twoctl billing-account` | [billing-account-api.yaml](openapi/billing-account-api.yaml) |
-| Repay | `twoctl repay` | [repay-api.yaml](openapi/repay-api.yaml) |
-| Recourse | `twoctl recourse` | [recourse-api.yaml](openapi/recourse-api.yaml) |
-| Company | `twoctl company` | [company-api.yaml](openapi/company-api.yaml) |
-| Limits | `twoctl limits` | [limits-api.yaml](openapi/limits-api.yaml) |
+Every operation across all six merchant-facing specs surfaces as a `twoctl
+<verb> <resource>` command. The verbs are auto-derived from operationId
+prefixes (get_/retrieve_/list_/search_, create_/make_/fulfill_/refund_/cancel_/...
+etc.), with HTTP-method fall-back when no prefix matches. Run
+`twoctl api-resources` for the full machine-readable catalog.
+
+| Spec | Source |
+| --- | --- |
+| Checkout (Order) | [checkout-api.yaml](openapi/checkout-api.yaml) |
+| Billing Account | [billing-account-api.yaml](openapi/billing-account-api.yaml) |
+| Repay | [repay-api.yaml](openapi/repay-api.yaml) |
+| Recourse | [recourse-api.yaml](openapi/recourse-api.yaml) |
+| Company | [company-api.yaml](openapi/company-api.yaml) |
+| Limits | [limits-api.yaml](openapi/limits-api.yaml) |
 
 ## Regeneration
 

cmd/twoctl/cli/auth.go

@@ -15,7 +15,11 @@ import (
 func init() {
 	authCmd := &cobra.Command{
 		Use:   "auth",
-		Short: "Manage API key authentication",
+		Short: "Manage API keys for the active context",
+		Long: `Store, remove, and inspect the API key for a context.
+
+By default, auth subcommands operate on the current context (set by
+` + "`twoctl ctx use`" + `). Pass --context to target a different one.`,
 	}
 	authCmd.AddCommand(
 		authLoginCmd(),
@@ -26,17 +30,15 @@ func init() {
 }
 
 func authLoginCmd() *cobra.Command {
-	var keyFlag string
+	var keyFlag, ctxFlag string
 	cmd := &cobra.Command{
 		Use:   "login",
-		Short: "Store an API key in the OS keychain",
-		Long: `Store a Two API key in the OS keychain (macOS Keychain, GNOME Keyring,
-Windows Credential Manager). The key is read from --key, or prompted for
-interactively if not provided.
-
-twoctl prefers the keychain over the TWO_API_KEY environment variable when
-both are set.`,
+		Short: "Store an API key in the OS keychain for a context",
 		RunE: func(cmd *cobra.Command, args []string) error {
+			target, err := pickContext(ctxFlag)
+			if err != nil {
+				return err
+			}
 			key := strings.TrimSpace(keyFlag)
 			if key == "" {
 				k, err := promptAPIKey(cmd)
@@ -48,47 +50,71 @@ both are set.`,
 			if !looksLikeAPIKey(key) {
 				return fmt.Errorf("that does not look like a Two API key (expected prefix secret_test_ or secret_prod_)")
 			}
-			if err := config.StoreKey(key); err != nil {
+			if err := config.StoreKey(target, key); err != nil {
 				return fmt.Errorf("storing key in keychain: %w", err)
 			}
-			fmt.Fprintln(cmd.OutOrStdout(), "stored API key in OS keychain")
+			fmt.Fprintf(cmd.OutOrStdout(), "stored API key for context %q\n", target)
 			return nil
 		},
 	}
 	cmd.Flags().StringVar(&keyFlag, "key", "", "API key to store (will prompt if omitted)")
+	cmd.Flags().StringVar(&ctxFlag, "context", "", "context to store the key under (default: current context)")
 	return cmd
 }
 
 func authLogoutCmd() *cobra.Command {
-	return &cobra.Command{
+	var ctxFlag string
+	cmd := &cobra.Command{
 		Use:   "logout",
-		Short: "Remove the API key from the OS keychain",
+		Short: "Remove the API key for a context",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := config.DeleteKey(); err != nil {
-				return fmt.Errorf("removing key: %w", err)
+			target, err := pickContext(ctxFlag)
+			if err != nil {
+				return err
+			}
+			if err := config.DeleteKey(target); err != nil {
+				return err
 			}
-			fmt.Fprintln(cmd.OutOrStdout(), "removed cached API key")
+			fmt.Fprintf(cmd.OutOrStdout(), "removed API key for context %q\n", target)
 			return nil
 		},
 	}
+	cmd.Flags().StringVar(&ctxFlag, "context", "", "context to forget (default: current context)")
+	return cmd
 }
 
 func authWhoamiCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "whoami",
-		Short: "Show which API key and environment will be used",
+		Short: "Show the active context, API URL, and key provenance",
 		RunE: func(cmd *cobra.Command, args []string) error {
-			resolved, err := config.Resolve(flagAPIKey, flagEnv)
+			resolved, err := config.Resolve(flagAPIKey, activeEnv(), flagURL)
 			if err != nil {
 				return err
 			}
-			fmt.Fprintf(cmd.OutOrStdout(), "environment: %s (%s)\nkey source:  %s\nkey prefix:  %s\n",
-				resolved.Env, resolved.Env.BaseURL(), resolved.Source, redact(resolved.APIKey))
+			fmt.Fprintf(cmd.OutOrStdout(), "context:    %s\nurl:        %s\nkey source: %s\nkey prefix: %s\n",
+				orDash(resolved.ContextName), resolved.BaseURL, resolved.Source, redactKey(resolved.APIKey))
 			return nil
 		},
 	}
 }
 
+// pickContext returns the explicit override if provided, otherwise the
+// current context name from config. Errors if neither is set.
+func pickContext(override string) (string, error) {
+	if override != "" {
+		return override, nil
+	}
+	cfg, err := config.LoadFile()
+	if err != nil {
+		return "", err
+	}
+	if cfg.CurrentContext == "" {
+		return "", fmt.Errorf("no current context - pass --context or run `twoctl ctx set <name> --url <url>`")
+	}
+	return cfg.CurrentContext, nil
+}
+
 func promptAPIKey(cmd *cobra.Command) (string, error) {
 	fmt.Fprint(cmd.OutOrStdout(), "Two API key: ")
 	if term.IsTerminal(int(os.Stdin.Fd())) {
@@ -114,18 +140,24 @@ func looksLikeAPIKey(s string) bool {
 		strings.HasPrefix(s, "secret_sandbox_")
 }
 
-// redact returns a key with everything between the env prefix and the last
-// four characters replaced by asterisks. Used for whoami output only.
-func redact(key string) string {
+// redactKey returns the key with everything between the env prefix and the
+// last four characters masked.
+func redactKey(key string) string {
 	if len(key) < 16 {
 		return "****"
 	}
-	prefix := key
 	tail := key[len(key)-4:]
 	if idx := strings.Index(key, "_"); idx >= 0 {
 		if idx2 := strings.Index(key[idx+1:], "_"); idx2 >= 0 {
-			prefix = key[:idx+1+idx2+1]
+			return key[:idx+1+idx2+1] + "****" + tail
 		}
 	}
-	return prefix + "****" + tail
+	return "****" + tail
+}
+
+func orDash(s string) string {
+	if s == "" {
+		return "-"
+	}
+	return s
 }