Skip to content

livery.workshop._shell

livery.workshop._shell

The entered-shell entry: a fully configured interactive shell.

fm shell [kind] makes the target shell itself evaluate fm -C=<root> --quiet env.emit <dialect> at its own startup, injected through a dialect-specific rc mechanism. The completion hook is a shell function that never survives an exec, so evaluating the emission in a wrapper and exec'ing the target would lose it; evaluated inside the target, environment and completion both land in the final interactive shell. A cold checkout fails loudly inside the opened shell: the emission's refusal prints to stderr, never a shell that merely looks entered.

The launch decisions are data (shell_launch_plan answers argv, environment, and rc files) so every branch tests as a plain call; the task body only writes and execs them.

Classes:

Name Description
ShellLaunch

Everything needed to open the entered shell, as pure data.

Functions:

Name Description
default_kind

The platform's interactive shell: $SHELL's basename, else pwsh/bash.

shell_launch_plan

The launch plan for an entered kind shell rooted at root.

launch_shell

Open the entered shell; never returns on POSIX, waits on Windows.

shell_default

Open an entered shell of kind (bash, zsh, or pwsh).

shell_prepare

Prepare an entered launch: write its rc files, answer its argv.

Attributes:

Name Type Description
shell

shell module-attribute

shell = group('shell', help='Open a fully entered interactive shell')

ShellLaunch dataclass

ShellLaunch(argv: list[str], env: dict[str, str] = dict(), files: dict[Path, str] = dict())

Everything needed to open the entered shell, as pure data.

Attributes:

Name Type Description
argv list[str]
env dict[str, str]
files dict[Path, str]

argv instance-attribute

argv: list[str]

env class-attribute instance-attribute

env: dict[str, str] = field(default_factory=dict)

files class-attribute instance-attribute

files: dict[Path, str] = field(default_factory=dict)

default_kind

default_kind() -> str

The platform's interactive shell: $SHELL's basename, else pwsh/bash.

Source code in packages/workshop/src/livery/workshop/_shell.py
def default_kind() -> str:
    """The platform's interactive shell: ``$SHELL``'s basename, else pwsh/bash."""
    if sys.platform == "win32":
        return "pwsh"
    name = Path(os.environ.get("SHELL", "")).name
    return name if name in _KINDS else "bash"

shell_launch_plan

shell_launch_plan(kind: str, *, root: Path, tmp_dir: Path) -> ShellLaunch

The launch plan for an entered kind shell rooted at root.

bash takes the injection through --rcfile (which replaces ~/.bashrc, so the rc sources it first; /etc rc files load regardless); zsh through a throwaway ZDOTDIR whose .zshenv and .zshrc chain to the user's own (ZDOTDIR resets to the home inside, so nested shells behave); pwsh through -NoExit -Command with the user profile still loading. cmd is refused: it has no startup file to inject, so a launched cmd only inherits a cold caller and looks entered without being entered; pwsh delivers the full contract on Windows.

Source code in packages/workshop/src/livery/workshop/_shell.py
def shell_launch_plan(kind: str, *, root: Path, tmp_dir: Path) -> ShellLaunch:
    """The launch plan for an entered *kind* shell rooted at *root*.

    bash takes the injection through ``--rcfile`` (which replaces
    ``~/.bashrc``, so the rc sources it first; ``/etc`` rc files
    load regardless); zsh through a throwaway ``ZDOTDIR`` whose
    ``.zshenv`` and ``.zshrc`` chain to the user's own (``ZDOTDIR``
    resets to the home inside, so nested shells behave); pwsh
    through ``-NoExit -Command`` with the user profile still
    loading. cmd is refused: it has no startup file to inject, so a
    launched cmd only inherits a cold caller and looks entered
    without being entered; pwsh delivers the full contract on
    Windows.
    """
    if kind == "cmd":
        raise SystemExit(
            "cmd has no startup file to evaluate the emission, so it"
            " cannot be entered reliably; use pwsh on Windows."
        )
    if kind not in _KINDS:
        raise SystemExit(f"unknown shell kind '{kind}' - one of: {', '.join(_KINDS)}")
    binary = _resolve_binary(kind)

    enter = _POSIX_ENTER.format(prog=footman.prog(), root=_posix_root(root))
    if kind == "bash":
        rc = tmp_dir / "livery-shell-bashrc"
        content = f'[ -f "$HOME/.bashrc" ] && . "$HOME/.bashrc"\n{enter}\n'
        return ShellLaunch(
            argv=[binary, "--rcfile", str(rc), "-i"], files={rc: content}
        )
    if kind == "zsh":
        zdot = tmp_dir / "livery-shell-zdot"
        zshenv = '[ -f "$HOME/.zshenv" ] && . "$HOME/.zshenv"\n'
        zshrc = (
            'ZDOTDIR="$HOME"\n'
            + '[ -f "$HOME/.zshrc" ] && . "$HOME/.zshrc"\n'
            + enter
            + "\n"
        )
        return ShellLaunch(
            argv=[binary, "-i"],
            env={"ZDOTDIR": str(zdot)},
            files={zdot / ".zshenv": zshenv, zdot / ".zshrc": zshrc},
        )
    return ShellLaunch(
        argv=[
            binary,
            "-NoLogo",
            "-NoExit",
            "-Command",
            _PWSH_ENTER.format(prog=footman.prog(), root=_pwsh_root(root)),
        ]
    )

launch_shell

launch_shell(kind: str = '') -> None

Open the entered shell; never returns on POSIX, waits on Windows.

POSIX execs, nothing left behind. Windows has no real exec, so the launcher waits and forwards the exit code: the console needs an owner.

Source code in packages/workshop/src/livery/workshop/_shell.py
def launch_shell(kind: str = "") -> None:
    """Open the entered shell; never returns on POSIX, waits on Windows.

    POSIX execs, nothing left behind. Windows has no real exec, so
    the launcher waits and forwards the exit code: the console needs
    an owner.
    """
    plan = _realise(kind)
    env = {**os.environ, **plan.env}
    if sys.platform == "win32":
        result = subprocess.run(plan.argv, env=env, cwd=os.getcwd(), check=False)
        raise SystemExit(result.returncode)
    os.execvpe(plan.argv[0], plan.argv, env)

shell_default

shell_default(kind: Arg[str] = '') -> None

Open an entered shell of kind (bash, zsh, or pwsh).

The launched shell evaluates fm env.emit at its own startup, so environment, PATH, and completion land inside it. Bare picks $SHELL's kind, pwsh on Windows.

Source code in packages/workshop/src/livery/workshop/_shell.py
@shell.default(interactive=True, shared=False)
def shell_default(
    kind: Arg[str] = "",
) -> None:
    """Open an entered shell of *kind* (bash, zsh, or pwsh).

    The launched shell evaluates ``fm env.emit`` at its own startup,
    so environment, PATH, and completion land inside it. Bare picks
    ``$SHELL``'s kind, pwsh on Windows.
    """
    launch_shell(kind)

shell_prepare

shell_prepare(kind: Arg[str] = '') -> Stdout[list[str]]

Prepare an entered launch: write its rc files, answer its argv.

The handoff for a launcher that must not keep a resident Python: the caller launches the argv itself. Writing the rc files here is the job, not a side errand; an argv naming a missing rc opens a shell that looks entered and is not. A plan that needs environment variables (zsh's throwaway ZDOTDIR) is refused rather than returned half-working.

Source code in packages/workshop/src/livery/workshop/_shell.py
@shell.task(name="prepare", hidden=True)
def shell_prepare(
    kind: Arg[str] = "",
) -> Stdout[list[str]]:
    """Prepare an entered launch: write its rc files, answer its argv.

    The handoff for a launcher that must not keep a resident Python:
    the caller launches the argv itself. Writing the rc files here
    is the job, not a side errand; an argv naming a missing rc opens
    a shell that looks entered and is not. A plan that needs
    environment variables (zsh's throwaway ``ZDOTDIR``) is refused
    rather than returned half-working.
    """
    plan = _realise(kind)
    if plan.env:
        names = ", ".join(sorted(plan.env))
        raise SystemExit(
            f"{kind or default_kind()} cannot be handed off as an argv:"
            f" it needs {names} set in the environment"
        )
    return plan.argv