Common

_common

Defines shared helpers for the CLI's Typer command implementations

Scope

• Centralises command output display using Rich

• Centralises error message display using Rich

• Maps the shared core's typed exceptions to Rich messages + Typer.Exit non-zero exits

StreamRender

Bounded, Docker-aware live renderer for streamed subprocess output

Why

Docker emits plain progress lines (one line per update) when its output is piped, producing a huge amount of output which grows a Rich table out of bounds

How It Works

• Per-layer progress lines are collapsed by layer id into a single in-place row, mirroring Docker's native console display, bounding the layer section to the image's layer count

• Every other line (build output, logs -f, git) goes to a bounded tail showing only the most recent lines

Parameters:

Name	Type	Description	Default
title	str	Heading shown above the rendered output	required
max_layers	int	Most layer rows to show at once	10
max_tail	int	Most non-layer lines to keep	8

__rich__()

Renders the current state as a rich group

Returns:

Type	Description
Group	A Group of the title, the collapsed layer rows, and the tail

add(line)

Routes a single output line into the layer map or the bounded tail

Parameters:

Name	Type	Description	Default
line	str	The raw output line to render	required

fail(message='Operation Aborted', code=1)

Console helper that prints errors with rich and returns a typer.Exit object for the launcher command to raise

Parameters:

Name	Type	Description	Default
messsage	str	Error message to display, formatted as ✗ {message}	required
code	int	The non-zero status to raise	1

Returns: A typer.Exit object carrying a non-zero status

require_env(backend, env_path)

Validates that every environment variable required by the chosen backend is configured

Read-Only

• The managed config is the source of truth

• The process' environment is used as a fallback (Compose applies the same precedence at runtime) so that a value supplied purely via the shell does not trigger a false "missing"

Parameters:

Name	Type	Description	Default
backend	Backend	The chosen transcription backend	required
env_path	Path	The managed config file to read	required

Raises:

Type	Description
Exit	If a required variable is set neither in the config nor in the process' environment

resolve_backend(flag, env_path)

Resolves which transcription backend should be used when running a CLI command

Order of Precedence

The values are considered in the following order

• Direct Flag Passed To Command (--transcribe)

• Value Stored In The Managed Config File

• Default (MODAL)

Parameters:

Name	Type	Description	Default
flag	Backend | None	The --transcribe value, if provided	required
env_path	Path	The managed config file to fall back to	required

Returns:

Type	Description
Backend	The backend to use for this run

resolve_source(flag, env_path)

Resolves which image source should be used when running a CLI command

Order of Precedence

The values are considered in the following order

• Direct Flag Passed To Command (--build/--pull)

• Value Stored In The Managed Config File

• Default (PULL)

Parameters:

Name	Type	Description	Default
flag	bool | None	True for --build, False for --pull, None when neither was passed	required
env_path	Path	The managed config file to fall back to	required

Returns:

Type	Description
ImageSource	The image source to use for this run

stream_command(gen, identifier, title, *, handle=None)

Consumes the streaming generator returned by core.process.stream, rendering each line through a bounded StreamRender and returning the process' return value. Maps launcher errors to clean Typer command exits

Cancellation

• When a StreamHandle is given (the same one passed to the streaming generator), output is consumed on a worker thread so that CTRL+C on the main thread can stop a stream that's blocked waiting for its next line (e.g. docker compose logs -f)

• The interrupt cancels the handle, killing the followed process, and exits cleanly

• Without a handle the generator is consumed in the same thread that's running this function

Parameters:

Name	Type	Description	Default
gen	Generator[str, None, T]	A generator yielding output lines	required
identifier	str	An identifier for the command being executed (e.g Docker)	required
title	str	The heading shown above the streamed output	required
handle	StreamHandle | None	The cancellation token bound to gen, enabling CTRL+C to stop a followed stream	None

Returns:

Type	Description
_T	The generator's return value

stream_logs(gen, identifier, *, handle=None, with_service=True)

Streams container logs straight to the console as a scrolling, themed view

Additional Information

• Unlike stream_command, this prints each line directly and lets the terminal's own scrollback hold the history

• Each line is coloured like the server console

• Also maps launcher errors to clean Typer exits

Parameters:

Name	Type	Description	Default
gen	Generator[str, None, T]	A generator yielding log lines	required
identifier	str	An identifier for the command (e.g Docker)	required
handle	StreamHandle | None	The cancellation token enabling CTRL+C to stop a followed (-f) stream	None
with_service	bool	Whether to highlight the docker service prefix (pass False when logs are filtered to a single service)	True

Returns:

Type	Description
_T	The generator's return value

subprocess_error_table(error, name, **table_kwargs)

Console helper that formats the information of a subprocess command failure as a table using rich

Parameters:

Name	Type	Description	Default
error	CalledProcessError	The subprocess exception raised by the command	required
name	str | None	Optional name to include in the table, formatted as ✗ {name} Command Failure	required
**table_kwargs	Any	Arguments overrides for rich.table.Table	{}

Returns:

Type	Description
Table	A rich.table.Table object with subprocess failure information