annie.system.reveal

Reveal a file in the OS file manager (service over the platform shell).

Annie is local-first — the browser and the filesystem are the same machine — so a “Show at location” button can open the user’s native file manager with the file selected. The command is platform-dependent:

• macOS → open -R <file> (Finder, file highlighted)

• Windows→ explorer /select,<file> (Explorer, file highlighted)

• other → xdg-open <dir> (opens the containing folder)

The command builder (reveal_command()) is pure and unit-tested; the thin reveal() wrapper spawns it.

Functions

is_docker(→ bool)	Return True when Annie is running inside a Docker container.
reveal_command(→ list[str])	Build the file-manager command that reveals path on platform.
reveal(→ None)	Open the OS file manager with path selected (fire-and-forget).

Module Contents

annie.system.reveal.is_docker(sentinel: pathlib.Path = _DOCKER_SENTINEL) → bool

Return True when Annie is running inside a Docker container.

Docker creates /.dockerenv in every container; its presence is the standard detection mechanism. The sentinel parameter exists solely to make this function testable without mocking.

Parameters:

sentinel – Path whose existence signals a Docker environment.

Returns:

True if the sentinel exists, False otherwise.

annie.system.reveal.reveal_command(path: str | pathlib.Path, platform: str) → list[str]

Build the file-manager command that reveals path on platform.

Parameters:

• path – The file (or folder) to reveal.

• platform – A sys.platform value ("darwin", "win32", …).

Returns:

The argv list to spawn. On unknown platforms the containing directory is opened with xdg-open.

annie.system.reveal.reveal(path: str | pathlib.Path) → None

Open the OS file manager with path selected (fire-and-forget).

Parameters:

path – The file to reveal.