TTY, Colour & Interactivity

import sys

stdin_is_tty = sys.stdin.isatty()
stdout_is_tty = sys.stdout.isatty()
stderr_is_tty = sys.stderr.isatty()

import java.io.Console;

final class Terminal {
    private Terminal() { }

    /** True when the JVM's console is a terminal. In Java 22+ System.console() may be non-null even when redirected. */
    static boolean isInteractive() {
        Console console = System.console();
        return console != null && console.isTerminal();
    }
}

import os
import sys
from typing import TextIO


def use_colour(stream: TextIO, *, no_color_flag: bool = False) -> bool:
    if no_color_flag:                       # --no-color always wins
        return False
    if os.environ.get("NO_COLOR"):          # set and non-empty
        return False
    if os.environ.get("TERM") == "dumb":
        return False
    return stream.isatty()                  # decide per stream


# docsctl writes errors to stderr, so colour them only if stderr is a terminal
ERROR_PREFIX = "\x1b[31merror:\x1b[0m" if use_colour(sys.stderr) else "error:"

from rich.console import Console


def make_error_console(no_color_flag: bool) -> Console:
    # no_color=None lets Rich auto-detect from NO_COLOR, TERM and whether stderr is a terminal
    return Console(stderr=True, no_color=True if no_color_flag else None)


console = make_error_console(no_color_flag=False)
console.print("[bold red]error:[/] component 'irurueta-algbra' not found")

final class ColourPolicy {
    private ColourPolicy() { }

    static boolean enabled(boolean noColorFlag, boolean stderrIsTerminal) {
        if (noColorFlag) {
            return false;
        }
        String noColor = System.getenv("NO_COLOR");
        if (noColor != null && !noColor.isEmpty()) {
            return false;
        }
        if ("dumb".equals(System.getenv("TERM"))) {
            return false;
        }
        return stderrIsTerminal;
    }
}

$ docsctl publish --component irurueta-algebra < /dev/null
docsctl: publishing 'irurueta-algebra' overwrites the live site and needs confirmation,
but there is no terminal to ask on.
Re-run with --yes to confirm, or preview the change first with --dry-run.
$ echo $?
5

import os
import sys

import typer

EXIT_CONFIRMATION_REQUIRED = 5


def is_interactive(no_input: bool) -> bool:
    if no_input or os.environ.get("DOCSCTL_NO_INPUT") == "1":
        return False
    return sys.stdin.isatty() and sys.stderr.isatty()


def confirm_publish(component: str, *, yes: bool, no_input: bool) -> None:
    if yes:
        return
    if not is_interactive(no_input):
        typer.echo(
            f"docsctl: publishing '{component}' overwrites the live site and needs confirmation, "
            "but there is no terminal to ask on.\n"
            "Re-run with --yes to confirm, or preview the change first with --dry-run.",
            err=True,
        )
        raise typer.Exit(code=EXIT_CONFIRMATION_REQUIRED)
    if not typer.confirm(f"Publish '{component}' to the live site?", default=False, err=True):
        raise typer.Exit(code=EXIT_CONFIRMATION_REQUIRED)  # the person declined

import java.io.Console;
import java.util.concurrent.Callable;

import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

@Command(name = "publish", description = "Publish a component to the site.")
final class PublishCommand implements Callable<Integer> {
    private static final int CONFIRMATION_REQUIRED = 5;

    @Option(names = "--component", required = true, paramLabel = "NAME")
    private String component;

    @Option(names = {"--yes", "-y"}, description = "Assume yes for confirmations.")
    private boolean yes;

    @Option(names = "--no-input", description = "Never prompt; fail if input would be needed.")
    private boolean noInput;

    private boolean interactive() {
        if (noInput || "1".equals(System.getenv("DOCSCTL_NO_INPUT"))) {
            return false;
        }
        Console console = System.console();
        return console != null && console.isTerminal(); // Java 22+; use console != null on Java 17-21
    }

    @Override
    public Integer call() {
        if (!yes) {
            if (!interactive()) {
                System.err.printf(
                    "docsctl: publishing '%s' overwrites the live site and needs confirmation, "
                        + "but there is no terminal to ask on.%n"
                        + "Re-run with --yes to confirm, or preview the change first with --dry-run.%n",
                    component);
                return CONFIRMATION_REQUIRED;
            }
            String answer = System.console().readLine("Publish '%s' to the live site? [y/N] ", component);
            if (answer == null || !answer.trim().equalsIgnoreCase("y")) {
                return CONFIRMATION_REQUIRED; // declined
            }
        }
        // ... perform the publish ...
        return 0;
    }

    public static void main(String[] args) {
        System.exit(new CommandLine(new PublishCommand()).execute(args));
    }
}

from rich.console import Console
from rich.progress import Progress


def index_pages(pages: list[str], *, quiet: bool, no_color: bool) -> None:
    console = Console(stderr=True, no_color=True if no_color else None)
    animated = console.is_terminal and not console.is_dumb_terminal and not quiet

    with Progress(console=console, transient=True, disable=not animated) as progress:
        task = progress.add_task("Indexing pages", total=len(pages))
        for page in pages:
            index_one(page)                     # the actual work
            progress.advance(task)

    if not animated and not quiet:
        console.print(f"Indexed {len(pages)} pages")  # one plain line for logs

final class Spinner implements AutoCloseable {
    private static final char[] FRAMES = {'|', '/', '-', '\\'};
    private final boolean animated;
    private int frame;

    Spinner(boolean stderrIsTerminal, boolean quiet) {
        this.animated = stderrIsTerminal && !quiet;
    }

    void tick(String message) {
        if (animated) {
            System.err.print("\r" + FRAMES[frame++ % FRAMES.length] + " " + message);
            System.err.flush();
        }
    }

    @Override
    public void close() {
        if (animated) {
            System.err.print("\r\u001b[2K"); // clear the line before the result is printed
            System.err.flush();
        }
    }
}