feat(tpagectl): add command examples #610

Merged

fuzzy merged 1 commit from feat/tpagectl-command-examples into main

2026-08-08 15:16:32 +00:00

automation commented

2026-08-08 15:12:21 +00:00

Owner

What

Implements Phase 8 command examples (roadmap #283).

New internal/tpagectl/examples — a pointer-keyed registry of usage examples per command. Apply(cmd, text) adds an --examples flag and wraps the command's Action so --examples prints the examples and returns successfully without running the command (works offline). Keying by command pointer avoids collisions between same-named subcommands (get/list/delete across groups).
--examples flag (#281) — added to all 18 leaf commands (site create/list/get/delete/update, deployment list/get/promote/rollback, preview list/deploy/delete/get, status, version, login, token set/clear), each with 2–4 realistic usage lines.
Help text (#282) — newCommand installs a custom cli.HelpPrinter that appends an EXAMPLES section to --help output (and the help subcommand) for registered commands.
Generated docs refreshed — docs/commands/*.md and docs/man/*.1 now list the --examples flag and include an Examples section.

Why

Roadmap task #283.

Testing

examples unit tests: --examples prints and short-circuits (underlying Action not run); without --examples the Action runs; Lookup/Flag; missing examples error
Command-level: site create --examples prints examples with no error; site create --help includes the EXAMPLES section and example text
Existing help tests pass unchanged (substring assertions)
go test -race ./... passes (30 packages)
golangci-lint run clean
pre-commit hooks pass (gofmt, go mod tidy, go test, trailing-whitespace, end-of-file)

Breaking Changes

None. --examples is additive; --help gains an EXAMPLES section.

Notes

urfave/cli v3 has no Examples field, so the registry is keyed by *cli.Command pointer; the docs generator reads it to include Examples in the generated Markdown/man pages.

Closes #281
Closes #282
Closes #283

## What Implements Phase 8 command examples (roadmap #283). - **New `internal/tpagectl/examples`** — a pointer-keyed registry of usage examples per command. `Apply(cmd, text)` adds an `--examples` flag and wraps the command's Action so `--examples` prints the examples and returns successfully without running the command (works offline). Keying by command pointer avoids collisions between same-named subcommands (`get`/`list`/`delete` across groups). - **`--examples` flag (#281)** — added to all 18 leaf commands (site create/list/get/delete/update, deployment list/get/promote/rollback, preview list/deploy/delete/get, status, version, login, token set/clear), each with 2–4 realistic usage lines. - **Help text (#282)** — `newCommand` installs a custom `cli.HelpPrinter` that appends an `EXAMPLES` section to `--help` output (and the `help` subcommand) for registered commands. - **Generated docs refreshed** — `docs/commands/*.md` and `docs/man/*.1` now list the `--examples` flag and include an Examples section. ## Why Roadmap task #283. ## Testing - [x] `examples` unit tests: `--examples` prints and short-circuits (underlying Action not run); without `--examples` the Action runs; `Lookup`/`Flag`; missing examples error - [x] Command-level: `site create --examples` prints examples with no error; `site create --help` includes the EXAMPLES section and example text - [x] Existing help tests pass unchanged (substring assertions) - [x] `go test -race ./...` passes (30 packages) - [x] `golangci-lint run` clean - [x] pre-commit hooks pass (gofmt, go mod tidy, go test, trailing-whitespace, end-of-file) ## Breaking Changes None. `--examples` is additive; `--help` gains an EXAMPLES section. ## Notes urfave/cli v3 has no `Examples` field, so the registry is keyed by `*cli.Command` pointer; the `docs` generator reads it to include Examples in the generated Markdown/man pages. Closes #281 Closes #282 Closes #283

automation added 1 commit

2026-08-08 15:12:22 +00:00

feat(tpagectl): add command examples

Test and Release / test (pull_request) Successful in 27s

Details

Test and Release / lint (pull_request) Successful in 27s

Details

0567cc784e

Add internal/tpagectl/examples: a pointer-keyed registry of usage examples
per command with an Apply helper that adds a --examples flag and short-
circuits the command's Action to print the examples (works offline).

- --examples (#281): wired into all 18 leaf commands (site, deployment,
  preview, status, version, login, token set/clear), each with 2-4
  realistic usage lines.
- Help text (#282): newCommand installs a HelpPrinter that appends an
  EXAMPLES section to --help output for registered commands.
- Generated docs (docs/commands, docs/man) now list the --examples flag
  and include an Examples section.

Closes #281
Closes #282
Closes #283

the.auditor referenced this pull request

2026-08-08 15:14:33 +00:00

--examples is not fully offline: root Before hook still bootstraps the client #611

the.auditor approved these changes

2026-08-08 15:14:45 +00:00

the.auditor left a comment

Clean examples system. The pointer-keyed registry neatly avoids collisions between same-named subcommands (get/list/delete), --examples short-circuits before the wrapped Action (so it wins over validation, e.g. token set --examples), the custom HelpPrinter appends an EXAMPLES section without disturbing existing help, and the docs generator picks up examples + the --examples flag (verified in regenerated docs/commands/tpagectl-site-create.md). version is included. Approving; one behavioral gap filed.

Suggestions

internal/tpagectl/examples/examples.go:32 – --examples short-circuits inside the Action, but the root Before hook (config load, newClient → keychain token resolve, TLS config) runs first. With a malformed config, a genuine keychain error, or a broken --ca-cert, --examples fails instead of printing — the "works offline" claim doesn't fully hold. Consider short-circuiting before client construction in the root Before. Filed as #611.

Notes

Regenerated leaf pages still carry the empty ## Subcommands header from #609 (separate issue, not this PR's scope).
cli.HelpPrinter is a package-global override set in newCommand(); safe for a single binary.

Praise

Apply preserves the original Action and mutates in place, keeping the wiring trivial and uniform across all 18 leaf commands.
Empty-registry path returns a validation error rather than silently printing nothing.
Docs examples render correctly in both Markdown (fenced) and roff (escaped) forms.

Clean examples system. The pointer-keyed registry neatly avoids collisions between same-named subcommands (`get`/`list`/`delete`), `--examples` short-circuits before the wrapped Action (so it wins over validation, e.g. `token set --examples`), the custom `HelpPrinter` appends an EXAMPLES section without disturbing existing help, and the docs generator picks up examples + the `--examples` flag (verified in regenerated `docs/commands/tpagectl-site-create.md`). `version` is included. Approving; one behavioral gap filed. ## Suggestions 1. `internal/tpagectl/examples/examples.go:32` – `--examples` short-circuits inside the Action, but the root `Before` hook (config load, `newClient` → keychain token resolve, TLS config) runs first. With a malformed config, a genuine keychain error, or a broken `--ca-cert`, `--examples` fails instead of printing — the "works offline" claim doesn't fully hold. Consider short-circuiting before client construction in the root `Before`. Filed as #611. ## Notes - Regenerated leaf pages still carry the empty `## Subcommands` header from #609 (separate issue, not this PR's scope). - `cli.HelpPrinter` is a package-global override set in `newCommand()`; safe for a single binary. ## Praise - `Apply` preserves the original Action and mutates in place, keeping the wiring trivial and uniform across all 18 leaf commands. - Empty-registry path returns a validation error rather than silently printing nothing. - Docs examples render correctly in both Markdown (fenced) and roff (escaped) forms.

fuzzy merged commit 0567cc784e into main

2026-08-08 15:16:32 +00:00

fuzzy deleted branch feat/tpagectl-command-examples

2026-08-08 15:16:32 +00:00