INF-1307 twoctl: spec-driven command-line for every Two API

A public Go CLI for the Two merchant APIs. Resource-verb command tree
(`twoctl <resource> <action>`) generated entirely from the published
OpenAPI specs in two-inc/docs, with auth, contexts, self-upgrade, and
agent-friendly UX out of the box.

API coverage
- Six merchant-facing APIs: checkout, billing-account, repay, recourse,
  company, limits. Every operationId surfaces as `twoctl <resource>
  <action>` with non-CRUD actions (cancel, refund, fulfill, search,
  notify, ...) as first-class verbs alongside get/create/edit/delete.
- Spec-driven: cmd/twoctl/cli embeds the six processed OpenAPI specs
  and walks them at startup. No per-operation Go code to maintain.
- internal/preprocess rewrites OAS 3.1 nullable patterns into a 3.0-
  compatible shape so the openapi3 parser can consume the upstream
  specs unchanged.

Contexts (kubectl-style)
- Named contexts each bundle a base URL and an OS-keychain entry.
  `twoctl config set-context / use-context / get-contexts /
  current-context / delete-context` manage them.
- Built-in env aliases: prod, sandbox, staging, cyber, perf, release.
  Unknown names fall back to https://api.<name>.two.inc.
- Per-invocation overrides without switching: --env / --context / --url
  / --api-key. Key resolution order: --api-key, TWO_API_KEY, keychain.
- Config at $XDG_CONFIG_HOME/twoctl or ~/.config/twoctl (XDG, never the
  macOS Library default).
- `twoctl auth login / logout / whoami` for keychain management.
- Keychain fallback detection: clear error when libsecret/DBus is
  missing on headless Linux instead of an opaque failure.

Agent + human UX
- `twoctl api-resources [--resource X] [--action Y]` emits a JSON
  catalog of every operation (command path, method, URL template,
  flags with kind/type/required, body status) for agent planners.
- `twoctl explain <resource> <action>` prints the operation's
  parameter, request body, and response schemas as JSON without a
  network call.
- `--describe` / `--dry-run` on every leaf operation. Dry-run prints
  the HTTP request that would be sent with sensitive headers redacted.
- `-o auto|table|json|yaml`: auto-detects TTY for default (table on
  terminal, json when piped). Tables render arrays of objects with
  union-of-keys columns; non-tabular shapes fall back to json.
- `--all` flag auto-registered on operations with `page_cursor`;
  follows `next_page_cursor` until exhausted and concatenates pages.
- Structured stderr error envelope: {error, message, status, response,
  request_id}. Captures upstream X-Request-Id / X-Trace-Id /
  X-Correlation-Id / Request-Id headers for support tickets.
- Stable exit codes: 0 ok, 1 generic, 2 usage, 3 auth, 4 not-found,
  5 rate-limited, 6 server, 7 network. Documented in README.
- Required parameters render as "(path, required)" in --help.
- Friendly HTTP error messages: 401 points at `twoctl auth login`,
  429 mentions rate limiting, 5xx suggests retry.

HTTP transport
- Shared transport injects X-Api-Key, User-Agent (`twoctl/<ver>
  (<os>/<arch>)`), and Accept on every call.
- Exponential backoff with jitter on 429 and 5xx, capped at 3 retries
  by default. Honours `Retry-After` header.
- Idempotency-Key (`twoctl-<hex>`) auto-set on POST/PUT/PATCH/DELETE
  so a retried mutation never duplicates.
- Request body buffered before send so retries can replay it.
- Response body capped at 4 MiB to prevent OOM on misbehaving servers.
- Context cancellation stops the retry loop cleanly.

Self-upgrade
- Once-per-day check on every invocation against the GitHub releases
  API. Network failures during the check are silent so they never
  block the actual command.
- Interactive prompt offers `y` install now / `n` not now / `s` skip
  this version. Skip list persists; `twoctl upgrade --reset-skips`
  clears it.
- Non-interactive shells (no TTY) get a single-line stderr nudge.
- `twoctl upgrade` runs the check + install on demand; `--check`,
  `--disable-autocheck`, `--enable-autocheck` available.
- `TWOCTL_SKIP_UPGRADE_CHECK=1` env var and `--no-upgrade-check` flag
  for scripts/CI.
- Binary swap via minio/selfupdate; supports tar.gz and zip archives.
- State persisted to ~/.config/twoctl/state.json.

Shell completion
- bash, zsh, fish, powershell via `twoctl completion <shell>`.
- Enum-valued OpenAPI parameters get value-completion registered
  automatically (e.g. tab-complete --country with ISO codes).

Tooling + CI
- Makefile with `build / install / regen / test / test-cover / lint /
  tidy / release-dry / clean`. `make help` self-documents.
- `make install` injects git describe --tags --always --dirty into the
  binary via ldflags so dev builds carry a version.
- scripts/lint.sh runs every Go Report Card tool (gofmt -s, go vet,
  ineffassign, misspell, gocyclo over 15, golint); exits non-zero on
  any output.
- CI: build + `make test-cover` gates coverage at 80% (currently
  81.3%) and the six-lint sweep runs on every PR.
- .github/workflows/regenerate.yml: repository_dispatch from
  two-inc/docs on openapi/* changes pulls fresh specs, runs codegen,
  opens a PR. Nightly cron as safety net; gracefully exits when
  DOCS_READ_TOKEN is unset.
- .github/workflows/release.yml + .goreleaser.yaml: tag push builds
  darwin/linux/windows binaries (amd64 + arm64) and updates the
  two-inc/homebrew-tap formula.
- docs/notify-twoctl.yml.example: drop-in workflow for two-inc/docs
  to fire the dispatch.

Telemetry stance
- No telemetry, no phone-home, no anonymous usage metrics. Outbound
  network calls are limited to the configured API endpoint and the
  GitHub releases API for upgrade checks. Documented in README.

Linear: https://linear.app/tillit/issue/INF-1307
Shared CLI patterns reference: https://linear.app/tillit/issue/INF-1314

Adversarial review applied (INF-1318)
- C1+C2+B1 self-update hardened: SHA-256 verified against published
  checksums.txt, strict regex asset selection, 100 MiB download + 200 MiB
  decompression caps, tar regular-file enforcement.
- C3 pagination max-page cap, cursor-seen-set, null-items guard.
- C4 response-cap fails loud (response_too_large) instead of truncating.
- C5 flag presence via cobra Flags().Changed (deliberate 0 / false sent).
- C6 path/query templating uses spec original parameter name.
- C7 redactKey conservative on non-API-key inputs.
- C8 normaliseURL rejects http://, query/fragment/userinfo, malformed URLs.
- C9 semver comparisons via golang.org/x/mod/semver.
- C10 looksLikeAPIKey is regex-strict (charset + length + no control chars).
- C11 README rewritten: removed phantom ctx/catalog commands.
- C12 dead apiMeta tree removed.
- O5 API key validation rejects embedded control characters.
- O7 redactHeaders allowlist matches any sensitive-looking header name.
- O8 error envelope redacts API-key-shaped values + sensitive JSON keys.
- O9 config dir 0o700, file 0o600.
- O11 context names validated against ^[a-z0-9][a-z0-9._-]{0,62}$.
- O13 crypto/rand failure panics (no predictable fallback for
  Idempotency-Key).
- V2+V3 built-in --describe/--dry-run/--all/--file/--data collisions
  detected and renamed at startup; spec params win.
- V6 stable disambiguator (operationId-derived suffix, not counter).
- V7 cross-spec resource collisions get API-name qualifier.
- V10 paginated body read once, not re-read per page.
- V12 json.Decoder.UseNumber + json.Number table cell → preserves IDs > 2^53.
- V16 --url drops context name so production key can't be sent to a typo URL.
- V19 isNullSchema accepts {type: null, description: ...} sibling decorations.
- Han-3+4+13 throttle persists NextCheckAt before network call; caches full
  Release payload to avoid double-fetch.
- Han-6 backoff attempt clamped to prevent shift overflow.
- Han-7 retry transport no longer mutates caller's req.Body.
- Han-8 Apply failure prints recovery hint pointing at releases page.
- Han-11 main() wires SIGINT to root context; in-flight requests cancel.

Author: brtkwr

.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: true
+      - run: go build ./...
+      - run: make test-cover
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: true
+      - name: Install lint tools
+        run: |
+          go install github.com/gordonklaus/ineffassign@latest
+          go install github.com/client9/misspell/cmd/misspell@latest
+          go install github.com/fzipp/gocyclo/cmd/gocyclo@latest
+          go install golang.org/x/lint/golint@latest
+          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
+      - run: ./scripts/lint.sh

.github/workflows/regenerate.yml

@@ -0,0 +1,68 @@
+name: regenerate
+
+# Pulls the latest OpenAPI specs from two-inc/docs and regenerates the
+# vendored copies + clients. Opens a PR if anything changed.
+#
+# Triggered by:
+#   - manual dispatch
+#   - repository_dispatch (event_type: openapi-updated), fired by a workflow
+#     in two-inc/docs whenever openapi/* files change on main.
+#   - nightly cron (safety net in case the dispatch is dropped)
+
+on:
+  workflow_dispatch: {}
+  repository_dispatch:
+    types: [openapi-updated]
+  schedule:
+    - cron: '0 3 * * *'
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  regen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: Fetch latest specs from two-inc/docs
+        env:
+          GH_TOKEN: ${{ secrets.DOCS_READ_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [[ -z "${GH_TOKEN:-}" ]]; then
+            echo "::notice::DOCS_READ_TOKEN not configured; skipping regeneration."
+            echo "Add a fine-grained PAT with read access to two-inc/docs as the"
+            echo "DOCS_READ_TOKEN repo secret to enable automatic regeneration."
+            exit 0
+          fi
+          for api in \
+            checkout billing-account repay recourse company limits \
+            autofill business-registration marketplace \
+            trade-account-v2 trade-account-v3 webhooks; do
+            gh api repos/two-inc/docs/contents/openapi/${api}-api.yaml \
+              --jq '.content' \
+              -H "Accept: application/vnd.github.v3+json" \
+              | base64 -d > openapi/${api}-api.yaml
+          done
+
+      - run: ./scripts/codegen.sh
+
+      - run: go build ./... && go vet ./...
+
+      - name: Open PR if changed
+        uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: 'chore: regenerate clients from latest openapi specs'
+          title: 'chore: regenerate clients from latest openapi specs'
+          branch: regen/openapi
+          delete-branch: true
+          body: |
+            Regenerated from the latest openapi specs in [two-inc/docs](https://github.com/two-inc/docs/tree/main/openapi).
+
+            This PR was opened automatically by the `regenerate` workflow.

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+          cache: true
+      - uses: goreleaser/goreleaser-action@v6
+        with:
+          version: latest
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,13 @@
+/dist/
+/bin/
+/twoctl
+*.test
+*.out
+.DS_Store
+.idea/
+.vscode/
+.worktrees/
+coverage.txt
+.build/
+/preprocess
+coverage.html

.goreleaser.yaml

@@ -0,0 +1,63 @@
+version: 2
+
+project_name: twoctl
+
+before:
+  hooks:
+    - go mod tidy
+
+builds:
+  - id: twoctl
+    main: ./cmd/twoctl
+    binary: twoctl
+    env:
+      - CGO_ENABLED=0
+    goos: [linux, darwin, windows]
+    goarch: [amd64, arm64]
+    ignore:
+      - goos: windows
+        goarch: arm64
+    ldflags:
+      - -s -w
+      - -X github.com/two-inc/twoctl-cli/internal/httpx.Version={{.Version}}
+
+archives:
+  - id: twoctl
+    name_template: >-
+      {{ .ProjectName }}_
+      {{- .Version }}_
+      {{- .Os }}_
+      {{- if eq .Arch "amd64" }}x86_64
+      {{- else if eq .Arch "386" }}i386
+      {{- else }}{{ .Arch }}{{ end }}
+    format_overrides:
+      - goos: windows
+        format: zip
+
+checksum:
+  name_template: 'checksums.txt'
+
+snapshot:
+  version_template: '{{ incpatch .Version }}-next'
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - '^docs:'
+      - '^test:'
+      - '^chore: regenerate'
+
+brews:
+  - name: twoctl
+    repository:
+      owner: two-inc
+      name: homebrew-tap
+      token: '{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}'
+    homepage: 'https://github.com/two-inc/twoctl'
+    description: 'Command-line interface for the Two merchant APIs'
+    license: MIT
+    install: |
+      bin.install "twoctl"
+    test: |
+      system "#{bin}/twoctl --version"

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Two AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,45 @@
+.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; fail if below COVERAGE_THRESHOLD (default 80).
+	go test -coverprofile=coverage.out -covermode=atomic ./...
+	@total=$$(go tool cover -func=coverage.out | awk '/^total:/ { sub(/%/, "", $$3); print $$3 }'); \
+	echo "total coverage: $$total%"; \
+	awk -v t=$$total -v thresh=$(COVERAGE_THRESHOLD) 'BEGIN { if (t+0 < thresh+0) { exit 1 } }' || \
+	  { echo "::error::coverage $$total% below threshold $(COVERAGE_THRESHOLD)%"; exit 1; }
+	@echo "html report: open coverage.html"
+	go tool cover -html=coverage.out -o coverage.html
+
+COVERAGE_THRESHOLD ?= 80
+
+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/