Skip to content

qtsone/learning / skills/tutor

tutor

Flagged

Turn this agent into a personal programming tutor with a versioned 0-to-expert curriculum (Go available; more languages coming). Use when the user wants to learn a programming language, start or resume lessons, get their exercise code graded, check learning progress, or contribute curriculum fixes — e.g. "/tutor go", "/tutor resume", "teach me Go", "continue my lessons", "grade my exercise".

FileKindSize
SKILL.mdskill md9.2 KB
curriculum/content/focus/cli-tooling/capstone/LESSON.mdmarkdown17.1 KB
curriculum/content/focus/cli-tooling/capstone/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/app.goscript5.8 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors.goscript1.6 KB
curriculum/content/focus/cli-tooling/capstone/exercise/authors_test.goscript7.3 KB
curriculum/content/focus/cli-tooling/capstone/exercise/cli_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/config_test.goscript11.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/go.modmanifest187 B
curriculum/content/focus/cli-tooling/capstone/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/capstone/exercise/main.goscript2.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/render.goscript1.9 KB
curriculum/content/focus/cli-tooling/capstone/exercise/root.goscript2.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan.goscript2.5 KB
curriculum/content/focus/cli-tooling/capstone/exercise/scan_test.goscript4.0 KB
curriculum/content/focus/cli-tooling/capstone/exercise/signal_unix_test.goscript1.4 KB
curriculum/content/focus/cli-tooling/capstone/exercise/version.goscript942 B
curriculum/content/focus/cli-tooling/capstone/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/capstone/solution/app.goscript9.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/authors.goscript2.9 KB
curriculum/content/focus/cli-tooling/capstone/solution/render.goscript2.6 KB
curriculum/content/focus/cli-tooling/capstone/solution/root.goscript4.7 KB
curriculum/content/focus/cli-tooling/capstone/solution/scan.goscript3.7 KB
curriculum/content/focus/cli-tooling/cobra/LESSON.mdmarkdown12.8 KB
curriculum/content/focus/cli-tooling/cobra/TUTOR.mdmarkdown5.9 KB
curriculum/content/focus/cli-tooling/cobra/exercise/app.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/exercise/go.modmanifest193 B
curriculum/content/focus/cli-tooling/cobra/exercise/go.summanifest900 B
curriculum/content/focus/cli-tooling/cobra/exercise/main.goscript422 B
curriculum/content/focus/cli-tooling/cobra/exercise/notes_test.goscript9.8 KB
curriculum/content/focus/cli-tooling/cobra/exercise/root.goscript919 B
curriculum/content/focus/cli-tooling/cobra/exercise/store.goscript1.7 KB
curriculum/content/focus/cli-tooling/cobra/quiz.jsonconfig5.1 KB
curriculum/content/focus/cli-tooling/cobra/solution/app.goscript2.4 KB
curriculum/content/focus/cli-tooling/cobra/solution/root.goscript4.2 KB
curriculum/content/focus/cli-tooling/distribution/LESSON.mdmarkdown17.2 KB
curriculum/content/focus/cli-tooling/distribution/TUTOR.mdmarkdown7.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/check.shexecutablescript12.0 KB
curriculum/content/focus/cli-tooling/distribution/exercise/go.modmanifest35 B
curriculum/content/focus/cli-tooling/distribution/exercise/internal/buildinfo/buildinfo.goscript1.4 KB
curriculum/content/focus/cli-tooling/distribution/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/distribution/quiz.jsonconfig5.0 KB
curriculum/content/focus/cli-tooling/distribution/solution/.goreleaser.yamlconfig2.1 KB
curriculum/content/focus/cli-tooling/distribution/solution/internal/buildinfo/buildinfo.goscript1.3 KB
curriculum/content/focus/cli-tooling/files-processes/LESSON.mdmarkdown18.8 KB
curriculum/content/focus/cli-tooling/files-processes/TUTOR.mdmarkdown7.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile.goscript772 B
curriculum/content/focus/cli-tooling/files-processes/exercise/atomicfile_test.goscript2.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec.goscript3.8 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/exec_test.goscript10.7 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/go.modmanifest44 B
curriculum/content/focus/cli-tooling/files-processes/exercise/main.goscript1.9 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/paths_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_test.goscript1.6 KB
curriculum/content/focus/cli-tooling/files-processes/exercise/signal_unix_test.goscript2.4 KB
curriculum/content/focus/cli-tooling/files-processes/quiz.jsonconfig7.9 KB
curriculum/content/focus/cli-tooling/files-processes/solution/atomicfile.goscript2.1 KB
curriculum/content/focus/cli-tooling/files-processes/solution/exec.goscript5.4 KB
curriculum/content/focus/cli-tooling/files-processes/solution/paths.goscript2.2 KB
curriculum/content/focus/cli-tooling/files-processes/solution/signal.goscript2.1 KB
curriculum/content/focus/cli-tooling/flags-config/LESSON.mdmarkdown12.3 KB
curriculum/content/focus/cli-tooling/flags-config/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config.goscript2.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/config_test.goscript3.1 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue.goscript769 B
curriculum/content/focus/cli-tooling/flags-config/exercise/flagvalue_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/go.modmanifest41 B
curriculum/content/focus/cli-tooling/flags-config/exercise/loader.goscript5.5 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/loader_test.goscript12.4 KB
curriculum/content/focus/cli-tooling/flags-config/exercise/main.goscript1.2 KB
curriculum/content/focus/cli-tooling/flags-config/quiz.jsonconfig5.3 KB
curriculum/content/focus/cli-tooling/flags-config/solution/config.goscript3.2 KB
curriculum/content/focus/cli-tooling/flags-config/solution/flagvalue.goscript957 B
curriculum/content/focus/cli-tooling/flags-config/solution/loader.goscript9.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/LESSON.mdmarkdown14.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/TUTOR.mdmarkdown6.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color.goscript1.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/color_test.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/go.modmanifest40 B
curriculum/content/focus/cli-tooling/terminal-ux/exercise/main.goscript3.6 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/progress_test.goscript1.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt.goscript2.3 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/prompt_test.goscript4.7 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render.goscript3.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/exercise/render_test.goscript6.1 KB
curriculum/content/focus/cli-tooling/terminal-ux/quiz.jsonconfig5.9 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/color.goscript1.8 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/progress.goscript2.0 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/prompt.goscript2.2 KB
curriculum/content/focus/cli-tooling/terminal-ux/solution/render.goscript4.3 KB
curriculum/content/focus/containers/capstone/LESSON.mdmarkdown20.0 KB
curriculum/content/focus/containers/capstone/TUTOR.mdmarkdown6.7 KB
curriculum/content/focus/containers/capstone/exercise/.dockerignoreother190 B
curriculum/content/focus/containers/capstone/exercise/.github/workflows/release.ymlconfig2.4 KB
curriculum/content/focus/containers/capstone/exercise/Dockerfileother903 B
curriculum/content/focus/containers/capstone/exercise/RUNBOOK.mdmarkdown1.6 KB
curriculum/content/focus/containers/capstone/exercise/check.shscript62.6 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/deployment.yamlconfig2.8 KB
curriculum/content/focus/containers/capstone/exercise/deploy/base/kustomization.yamlconfig845 B
curriculum/content/focus/containers/capstone/exercise/deploy/base/service.yamlconfig316 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/kustomization.yamlconfig1.3 KB
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/dev/resources-patch.yamlconfig906 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/kustomization.yamlconfig899 B
curriculum/content/focus/containers/capstone/exercise/deploy/overlays/prod/resources-patch.yamlconfig341 B
curriculum/content/focus/containers/capstone/exercise/go.modmanifest48 B
curriculum/content/focus/containers/capstone/exercise/main.goscript6.4 KB
curriculum/content/focus/containers/capstone/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/capstone/solution/.github/workflows/release.ymlconfig6.4 KB
curriculum/content/focus/containers/capstone/solution/Dockerfileother1.2 KB
curriculum/content/focus/containers/capstone/solution/RUNBOOK.mdmarkdown7.7 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/kustomization.yamlconfig1.4 KB
curriculum/content/focus/containers/capstone/solution/deploy/overlays/prod/resources-patch.yamlconfig1.1 KB
curriculum/content/focus/containers/compose/LESSON.mdmarkdown13.5 KB
curriculum/content/focus/containers/compose/TUTOR.mdmarkdown5.2 KB
curriculum/content/focus/containers/compose/exercise/.env.exampleother348 B
curriculum/content/focus/containers/compose/exercise/app/Dockerfileother962 B
curriculum/content/focus/containers/compose/exercise/app/go.modmanifest40 B
curriculum/content/focus/containers/compose/exercise/app/main.goscript2.2 KB
curriculum/content/focus/containers/compose/exercise/check.shscript24.5 KB
curriculum/content/focus/containers/compose/exercise/compose.yamlconfig877 B
curriculum/content/focus/containers/compose/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/compose/solution/.envconfig203 B
curriculum/content/focus/containers/compose/solution/compose.yamlconfig1.6 KB
curriculum/content/focus/containers/deploying-go/LESSON.mdmarkdown21.1 KB
curriculum/content/focus/containers/deploying-go/TUTOR.mdmarkdown6.5 KB
curriculum/content/focus/containers/deploying-go/exercise/.dockerignoreother150 B
curriculum/content/focus/containers/deploying-go/exercise/Dockerfileother851 B
curriculum/content/focus/containers/deploying-go/exercise/SHUTDOWN.mdmarkdown1.4 KB
curriculum/content/focus/containers/deploying-go/exercise/check.shscript43.5 KB
curriculum/content/focus/containers/deploying-go/exercise/configmap.yamlconfig526 B
curriculum/content/focus/containers/deploying-go/exercise/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/deploying-go/exercise/go.modmanifest41 B
curriculum/content/focus/containers/deploying-go/exercise/main.goscript6.1 KB
curriculum/content/focus/containers/deploying-go/exercise/service.yamlconfig347 B
curriculum/content/focus/containers/deploying-go/exercise/shutdown_test.goscript3.3 KB
curriculum/content/focus/containers/deploying-go/quiz.jsonconfig6.5 KB
curriculum/content/focus/containers/deploying-go/solution/SHUTDOWN.mdmarkdown5.4 KB
curriculum/content/focus/containers/deploying-go/solution/configmap.yamlconfig541 B
curriculum/content/focus/containers/deploying-go/solution/deployment.yamlconfig4.0 KB
curriculum/content/focus/containers/deploying-go/solution/main.goscript6.1 KB
curriculum/content/focus/containers/docker-fundamentals/LESSON.mdmarkdown14.4 KB
curriculum/content/focus/containers/docker-fundamentals/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/Dockerfileother261 B
curriculum/content/focus/containers/docker-fundamentals/exercise/NOTES.mdmarkdown1.4 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/check.shscript10.7 KB
curriculum/content/focus/containers/docker-fundamentals/exercise/go.modmanifest38 B
curriculum/content/focus/containers/docker-fundamentals/exercise/local.envconfig218 B
curriculum/content/focus/containers/docker-fundamentals/exercise/main.goscript780 B
curriculum/content/focus/containers/docker-fundamentals/exercise/scratch/notes.mdmarkdown153 B
curriculum/content/focus/containers/docker-fundamentals/quiz.jsonconfig5.5 KB
curriculum/content/focus/containers/docker-fundamentals/solution/.dockerignoreother230 B
curriculum/content/focus/containers/docker-fundamentals/solution/Dockerfileother504 B
curriculum/content/focus/containers/docker-fundamentals/solution/NOTES.mdmarkdown3.8 KB
curriculum/content/focus/containers/dockerizing-go/LESSON.mdmarkdown14.0 KB
curriculum/content/focus/containers/dockerizing-go/TUTOR.mdmarkdown5.4 KB
curriculum/content/focus/containers/dockerizing-go/exercise/.dockerignoreother143 B
curriculum/content/focus/containers/dockerizing-go/exercise/Dockerfile.naiveother512 B
curriculum/content/focus/containers/dockerizing-go/exercise/NOTES.mdmarkdown1.1 KB
curriculum/content/focus/containers/dockerizing-go/exercise/check.shscript14.2 KB
curriculum/content/focus/containers/dockerizing-go/exercise/go.modmanifest43 B
curriculum/content/focus/containers/dockerizing-go/exercise/go.summanifest0 B
curriculum/content/focus/containers/dockerizing-go/exercise/main.goscript1.7 KB
curriculum/content/focus/containers/dockerizing-go/quiz.jsonconfig4.5 KB
curriculum/content/focus/containers/dockerizing-go/solution/Dockerfileother755 B
curriculum/content/focus/containers/dockerizing-go/solution/NOTES.mdmarkdown2.7 KB
curriculum/content/focus/containers/helm-kustomize/LESSON.mdmarkdown19.1 KB
curriculum/content/focus/containers/helm-kustomize/TUTOR.mdmarkdown9.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/NOTES.mdmarkdown1.5 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/Chart.yamlconfig518 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/_helpers.tplother1.8 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/configmap.yamlconfig392 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/deployment.yamlconfig3.2 KB
curriculum/content/focus/containers/helm-kustomize/exercise/chart/templates/service.yamlconfig512 B
curriculum/content/focus/containers/helm-kustomize/exercise/chart/values.yamlconfig1.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/check.shscript55.4 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/deployment.yamlconfig2.1 KB
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/kustomization.yamlconfig798 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/base/service.yamlconfig347 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/kustomization.yamlconfig616 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/dev/resources-patch.yamlconfig506 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/kustomization.yamlconfig477 B
curriculum/content/focus/containers/helm-kustomize/exercise/kustomize/overlays/prod/resources-patch.yamlconfig614 B
curriculum/content/focus/containers/helm-kustomize/quiz.jsonconfig7.4 KB
curriculum/content/focus/containers/helm-kustomize/solution/NOTES.mdmarkdown3.3 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/Chart.yamlconfig366 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/configmap.yamlconfig547 B
curriculum/content/focus/containers/helm-kustomize/solution/chart/templates/deployment.yamlconfig2.5 KB
curriculum/content/focus/containers/helm-kustomize/solution/chart/values.yamlconfig1.2 KB
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/base/kustomization.yamlconfig915 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/kustomization.yamlconfig820 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/dev/resources-patch.yamlconfig515 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/kustomization.yamlconfig267 B
curriculum/content/focus/containers/helm-kustomize/solution/kustomize/overlays/prod/resources-patch.yamlconfig649 B
curriculum/content/focus/containers/kubernetes-config/LESSON.mdmarkdown19.4 KB
curriculum/content/focus/containers/kubernetes-config/TUTOR.mdmarkdown6.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/NOTES.mdmarkdown1.3 KB
curriculum/content/focus/containers/kubernetes-config/exercise/app/Dockerfileother1.0 KB

curriculum/content/focus/cli-tooling/terminal-ux/LESSON.md

View on GitHub
# Terminal UX

> `focus.cli.terminal-ux` · ~3-4h · Stage: Focus: CLI Tooling

## Objectives

By the end of this lesson you can:

- Detect whether output is a TTY and degrade gracefully — no colors or progress
  animations when piped or redirected.
- Render styled ANSI output while honoring the NO_COLOR convention and a
  `--no-color` flag.
- Implement an interactive prompt with input validation and a sensible default
  value.
- Implement a progress indicator for a long-running operation that writes to
  stderr, leaving stdout clean for data.
- Explain what a TUI framework's model-update-view loop (Bubble Tea and
  friends) adds over line-based output, and identify when it is overkill.

## Two streams, two audiences

Your program has two output streams and they are not interchangeable:

- **stdout carries data** — the thing the user asked for. It is what flows into
  the next command in a pipeline.
- **stderr carries diagnostics** — progress, warnings, errors, prompts.
  Everything *about* the run rather than *of* the run.

That split is the whole reason `tool | jq .` and `tool > out.txt 2> log.txt`
work. Put a progress bar on stdout and you have corrupted your user's data.
Put the results on stderr and the pipeline downstream gets nothing.

The rule of thumb: *if a script would want to parse it, it goes on stdout;
if a human would want to read it while the program runs, it goes on stderr.*
The third channel is the exit code — 0 for success, non-zero for failure —
which is how `&&` and CI decide what happens next.

You already have the shape for this. Your S3 link checker was entered through
`Run(args []string, stdin io.Reader, stdout, stderr io.Writer) int`, and in the
Cobra lesson you fed commands with `SetOut`/`SetErr`. This lesson is about what
you *write* into those two writers.

## Never reach for os.Stdout

Once a package writes to `os.Stdout` directly, the only way to test its output
is to hijack a global, and the only way to reuse it elsewhere is not at all.
Take writers as parameters and let exactly one function — `main` — know that
the real ones come from `os`:

```go
func main() {
	os.Exit(run(os.Args[1:], os.Stdin, os.Stdout, os.Stderr))
}
```

`io.Discard` then becomes your off switch: passing it instead of `os.Stderr`
silences a component without a single `if quiet` inside it.

## Is anyone watching?

A terminal renders escape sequences; a file, a pipe, and a CI log do not. So
before styling anything you have to ask whether the stream on the other end is
a terminal. The stdlib answer is a file-mode check:

```go
func isTerminal(f *os.File) bool {
	info, err := f.Stat()
	if err != nil {
		return false
	}
	return info.Mode()&os.ModeCharDevice != 0
}
```

Two honest caveats: this asks "is it a character device?", which is true for
terminals *and* for `/dev/null`; and on Windows the console needs extra work
before it interprets escapes at all. The precise answer is an ioctl, and
`golang.org/x/term.IsTerminal(int(f.Fd()))` is the tiny, well-maintained
dependency that does it properly on every platform.

Whichever you use, the important design move is the same: **detection happens
once, at the edge, and everything below it receives a plain `bool`.** That is
what makes the rest of the program testable — a test can say "pretend this is a
terminal" without owning a terminal. Note also that stdin, stdout, and stderr
are redirected independently, so you may need three answers: colour the results
by whether *stdout* is a terminal, draw progress by whether *stderr* is, and
prompt by whether *stdin* is.

## ANSI in one page

Styling is done with escape sequences the terminal interprets instead of
printing. They start with the escape character `\x1b` (ESC), then `[` — the
pair is called CSI, Control Sequence Introducer — then parameters, then a
letter that says what to do. For colour and style the letter is `m` (SGR,
Select Graphic Rendition):

```go
const (
	Reset = "\x1b[0m"   // turn every attribute off
	Bold  = "\x1b[1m"
	Dim   = "\x1b[2m"
	Red   = "\x1b[31m"  // 30-37 foreground, 40-47 background,
	Green = "\x1b[32m"  // 90-97 the bright variants
)

fmt.Println(Red + Bold + "error" + Reset + ": file not found")
```

There are also 256-colour (`\x1b[38;5;<n>m`) and 24-bit
(`\x1b[38;2;<r>;<g>;<b>m`) forms, but the basic palette is what users have
themed and what every terminal renders — reach past it rarely.

Three rules save you most of the pain:

1. **Always reset.** An unclosed attribute leaks into the user's shell prompt.
2. **Escape sequences have no width.** `\x1b[32mok\x1b[0m` is 11 bytes and two
   columns. `fmt.Sprintf("%-4s", painted)` pads by the length of the string it
   is handed — counting the nine invisible escape characters as if they
   occupied columns — and destroys your alignment: pad by the visible text,
   then paint.
3. **Cursor control is not colour.** `\r` (carriage return) and `\x1b[K`
   (erase to end of line) move and clear rather than decorate. `NO_COLOR` has
   no say over them, but a non-terminal stream must not see them either.

## The colour decision is policy

Whether to emit those bytes is a decision with several inputs, and — exactly as
in the flags-and-configuration lesson — the value of a precedence chain is that
it is *written down* and testable:

1. `--color=never` / `--no-color` → off. The user said no.
2. `--color=always` → on. The user said yes, even into a pipe (this is how
   `tool --color=always | less -R` works).
3. `NO_COLOR` set to a non-empty value → off. This is a cross-tool convention
   (see no-color.org): users set it once and every well-behaved program obeys.
   An explicit flag on *this* invocation is more specific than an environment
   default, which is why it sits above.
4. `TERM=dumb` → off. The terminal has told you it cannot render escapes.
5. Otherwise → on only if the stream is a terminal.

Two practical notes. Take the environment as a `func(string) (string, bool)`
parameter rather than calling `os.LookupEnv` deep in the code: the policy then
tests as a pure function. And keep colour *out* of machine-readable output
unconditionally — a `--json` run must never emit an escape byte, whatever the
flags say.

## Quiet and verbose

Verbosity is a level, not a pile of booleans:

```go
const (
	LevelQuiet Level = iota
	LevelNormal
	LevelVerbose
)
```

The gate applies to the *diagnostic* stream only. **Data** is the program's
product, so quiet mode never suppresses it, and **errors** are never suppressed
either — a silent failure is a bug report you receive next quarter. What the
level gates is **info** (what is happening, normal and above) and **debug**
(how it is happening, only when asked). Two flags, `-q` and `-v`, cover almost
every real tool; resist inventing five levels nobody can remember.

## Progress that behaves

A progress line is a single line rewritten in place: return the cursor to
column 0 with `\r`, print the new status, and erase whatever the previous,
longer status left behind with `\x1b[K`:

```go
fmt.Fprintf(w, "\r%s: %d/%d (%d%%)\x1b[K", label, n, total, n*100/total)
```

It goes to **stderr**, so that `tool > results.txt` still shows progress and
`tool | wc -l` still counts the right thing.

When the stream is not a terminal, the animation is not just useless but
actively harmful: a CI log ends up with ten thousand identical lines full of
control characters. Degrade to nothing during the run and one plain summary
line at the end. That is the general shape of graceful degradation — *the
information survives, the decoration does not*.

Keep the reporter driven by explicit `Update` calls from the work loop rather
than by a background timer. A timer means a goroutine, wall-clock flakiness,
and a test that cannot assert bytes; explicit calls mean the same input always
produces the same output. (Real tools throttle redraws — "at most every 100ms"
— but that belongs outside the piece you are testing.) Two details worth
knowing: a status line longer than the terminal wraps and breaks the redraw, so
truncate it; and a program killed mid-draw can leave a hidden cursor behind,
which is signal handling — the next lesson in this pack.

## Prompts

An interactive prompt is the same discipline again: write the question to
stderr, read the answer from an injected reader, and treat "there is no
terminal" as a first-class case.

- Show the default in brackets — `Region [eu-west-1]: ` — and let an empty
  answer take it. If the user has to type the default, it is not a default.
- Validate, and on rejection say what was wrong and ask again. Cap the retries
  so a broken loop terminates.
- **Never block on a prompt when stdin is not a terminal.** Use the default, or
  fail with an error naming the flag that supplies the value. A tool that hangs
  in CI waiting for an answer nobody can give is the classic version of this
  bug; `--yes` exists for exactly this reason.
- Create the `bufio.Scanner` (or `bufio.Reader`) **once**, in the constructor.
  A fresh one per question keeps whatever it buffered past the newline, and
  your second question silently eats the answer to the third.
- For secrets, don't echo: `golang.org/x/term.ReadPassword` turns echo off and
  restores it. Rolling that yourself with raw terminal modes is not worth it.

## Machine-readable output

Every tool worth scripting has a `--json` mode, and the reason is a contract:

> The human format is not an API. The machine format is.

You may realign columns, add colour, or reword a summary in a patch release.
The JSON shape is something other people's scripts depend on, so it changes
only the way an API changes.

Practical rules, all of them exercised by this lesson's tests:

- JSON goes on **stdout, alone**. Diagnostics stay on stderr, so
  `tool --json 2>/dev/null | jq` never sees a stray log line.
- Emit a **document**, not a bare array: `{"results": [...]}` can grow a
  `"version"` or `"summary"` field later; `[...]` cannot.
- Beware `null`. A nil slice marshals to `null`, and every consumer that loops
  over the array breaks on it. Encode an empty slice.
- Never style it. See the previous section.
- For a stream of events, one JSON object per line (NDJSON) lets consumers
  process results as they arrive instead of waiting for the closing brace.

## When a TUI is the wrong answer

Bubble Tea and its ecosystem (Lip Gloss for styling, Bubbles for widgets)
implement the Elm architecture: your program is a `Model`, an `Update(msg)`
that returns a new model plus commands, and a `View()` that renders the whole
screen as a string. The framework owns the event loop, the alternate screen
buffer, raw input, and repainting — which is genuinely hard to hand-roll, and
the right call for a long-lived interactive session: a file browser, a log
explorer, a git client.

It is the wrong answer for most CLI tools, and the reasons are the same ones
this lesson has been about. A full-screen app is not pipeable, not greppable,
not scriptable, and awkward in CI, over a poor ssh link, in a dumb terminal, or
with a screen reader. It is also markedly harder to test than a function that
writes bytes to an `io.Writer`. If the interaction is "run, do work, report",
line-based output with good degradation serves users better and costs less.
Reach for a TUI when the user's job is to *stay* in your program, not to pass
through it.

## Exercise

Open [`exercise/`](exercise/) — a module with four work files and their tests.
`main.go` is complete and shows the wiring: it is the only file that touches
`os`, and it hands everything below three writers and three booleans.

Read the tests first; they pin the exact bytes.

- `color.go` — `ParseColorMode` and `ResolveColor`, the precedence chain.
- `render.go` — `Renderer`: `Paint`, `Out`, `Info`, `Debug`, `Errorf`,
  `Results`.
- `progress.go` — `Progress`: `Update`, `Done`.
- `prompt.go` — `Prompter.Ask`.

Acceptance criteria:

1. `ParseColorMode` accepts `"auto"`, `"always"` and `"never"`, and returns an
   error naming the bad value otherwise.
2. `ResolveColor` implements the documented chain: `never` off, `always` on
   (beating `NO_COLOR`), non-empty `NO_COLOR` off, `TERM=dumb` off, otherwise
   the terminal answer. `NO_COLOR` set to the empty string is not a veto.
3. `Paint` wraps text in the given codes plus one `Reset` when colour is on,
   returns it unchanged when colour is off, and never emits a lone `Reset`.
   The provided `main.go` folds its `--no-color` shorthand into the same
   chain by mapping it to `never` — read that wiring and be ready to say why
   the shorthand exists alongside the three-valued `--color`.
4. `Out` writes data to stdout at every level; `Info` writes to stderr at
   normal and above; `Debug` only at verbose; `Errorf` writes to stderr at
   every level with a `Red`+`Bold` `error:` prefix.
5. `Results` in human mode writes one line per result, `ok` green and `fail`
   red, with the status padded to four visible columns so coloured and plain
   output align identically.
6. `Results` in JSON mode writes one compact `Report` line on stdout with no
   escape sequences even when colour is on, and encodes an empty result set as
   `{"results":[]}`. Both modes report write errors.
7. `Progress` on a terminal redraws `\r<status>\x1b[K` per `Update` and leaves
   a `done` summary line; off a terminal it writes nothing until `Done`, then
   one plain summary with no `\r` and no escapes. An unknown total (0) reports
   a count instead of a percentage.
8. `Ask` prints `question [default]: ` (or `question: `), trims the answer,
   takes the default on an empty one, re-asks with an `error: …` line on
   validation failure up to `MaxPromptAttempts` before returning
   `ErrTooManyAttempts`, returns the default without touching the streams when
   there is no terminal, and returns `ErrNotInteractive` when there is neither
   terminal nor default. Consecutive questions read consecutive lines.
9. `go test ./...` passes and the code is `gofmt`-clean.

Run the tests from inside `exercise/`:

```sh
cd exercise
go test ./...
```

They fail on the starter. When they are green, build the demo and look at it
with your own eyes — the difference between the two runs is the lesson:

```sh
go build -o scan . && ./scan          # a terminal: colour and a live line
./scan | cat                          # a pipe: plain, quiet, parseable
./scan --json | cat
NO_COLOR=1 ./scan
```

## Further reading

- [no-color.org](https://no-color.org/) — the convention, in about ten lines.
- [Command Line Interface Guidelines](https://clig.dev/) — the best single
  write-up of CLI conventions; the output and interactivity sections cover
  exactly this lesson's ground.
- [pkg.go.dev — golang.org/x/term](https://pkg.go.dev/golang.org/x/term) —
  `IsTerminal`, `GetSize`, `ReadPassword`.
- [XTerm control sequences](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html)
  — the reference for what those escape codes actually mean.
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) — read the tutorial
  to see the model-update-view loop, then decide honestly whether your tool
  needs one.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall