lab-env 0.0.2__py3-none-any.whl

lab_env/__init__.py

@@ -0,0 +1,10 @@
+"""Tools for consistent research computing environments."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("lab-env")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

lab_env/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for lab-env."""
+
+from lab_env.cli.app import app
+
+__all__ = ["app"]

lab_env/cli/app.py

@@ -0,0 +1,90 @@
+"""Typer application for the lab-env command-line interface."""
+
+# --------------------------------------------------
+# import necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from lab_env.cli.callbacks import version_callback
+from lab_env.cli.cmd_doctor import cmd_doctor
+from lab_env.cli.cmd_hosts import cmd_hosts
+from lab_env.cli.cmd_init import cmd_init
+from lab_env.cli.cmd_remote import cmd_connect, cmd_pull, cmd_push
+from lab_env.cli.cmd_shell import shell_app
+from lab_env.cli.context import CliContext
+from lab_env.config import default_config_path
+
+# --------------------------------------------------
+# create Typer application
+# --------------------------------------------------
+app = typer.Typer(
+    name="lab",
+    help="Set up and inspect consistent research computing environments.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+# --------------------------------------------------
+# callbacks: defined in callbacks.py
+#   - version_callback: handles the --version option
+# --------------------------------------------------
+@app.callback()
+def main(
+    context: typer.Context,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            help="Personal TOML configuration path.",
+            dir_okay=False,
+        ),
+    ] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=version_callback,
+            is_eager=True,
+            help="Show the installed version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Configure shared state for lab-env commands."""
+
+    del version
+    context.obj = CliContext(config_path=config or default_config_path())
+
+
+# --------------------------------------------------
+# register commands: provided in cmd_*.py modules
+# --------------------------------------------------
+
+# init command
+app.command(name="init", rich_help_panel="Configuration")(cmd_init)
+
+# hosts command
+app.command(name="hosts", rich_help_panel="Configuration")(cmd_hosts)
+
+# doctor command
+app.command(name="doctor", rich_help_panel="Diagnostics")(cmd_doctor)
+
+# remote commands
+app.command(name="connect", rich_help_panel="Remote")(cmd_connect)
+app.command(name="pull", rich_help_panel="Remote")(cmd_pull)
+app.command(name="push", rich_help_panel="Remote")(cmd_push)
+
+# shell command
+app.add_typer(shell_app, name="shell", rich_help_panel="Shell")
+
+# --------------------------------------------------
+# main entry point
+# --------------------------------------------------
+if __name__ == "__main__":
+    app()

lab_env/cli/callbacks.py

@@ -0,0 +1,15 @@
+"""Shared callbacks for the lab-env command-line interface."""
+
+from __future__ import annotations
+
+import typer
+
+from lab_env import __version__
+
+
+def version_callback(value: bool) -> None:
+    """Print the installed package version and exit."""
+
+    if value:
+        typer.echo(f"lab {__version__}")
+        raise typer.Exit()

lab_env/cli/cmd_doctor.py

@@ -0,0 +1,20 @@
+"""Run local lab-env diagnostics."""
+
+from __future__ import annotations
+
+import typer
+
+from lab_env.cli.context import CliContext
+from lab_env.diagnostics import run_diagnostics
+
+
+def cmd_doctor(context: typer.Context) -> None:
+    """Check local configuration and tools without network activity."""
+
+    cli_context: CliContext = context.obj
+    results = run_diagnostics(cli_context.config_path)
+    for result in results:
+        typer.echo(f"[{result.status}] {result.name}: {result.detail}")
+
+    if any(result.status == "error" for result in results):
+        raise typer.Exit(1)

lab_env/cli/cmd_hosts.py

@@ -0,0 +1,27 @@
+"""List configured lab host aliases."""
+
+from __future__ import annotations
+
+import typer
+
+from lab_env.cli.context import CliContext
+from lab_env.config import ConfigError, load_config
+
+
+def cmd_hosts(context: typer.Context) -> None:
+    """List configured host aliases without making connections."""
+
+    cli_context: CliContext = context.obj
+    try:
+        config = load_config(cli_context.config_path)
+    except ConfigError as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(2) from error
+
+    if not config.hosts:
+        typer.echo("no hosts configured")
+        return
+
+    for host_name, host in sorted(config.hosts.items()):
+        description = f" - {host.description}" if host.description else ""
+        typer.echo(f"{host_name}: {host.destination}{description}")

lab_env/cli/cmd_init.py

@@ -0,0 +1,34 @@
+"""Initialize a personal lab-env configuration."""
+
+# --------------------------------------------------
+# load necessary modules
+# --------------------------------------------------
+from __future__ import annotations
+
+import typer
+
+from lab_env.cli.context import CliContext
+from lab_env.config import initialize_config
+
+
+# --------------------------------------------------
+# init command
+# --------------------------------------------------
+def cmd_init(context: typer.Context) -> None:
+    """Create a personal configuration file without changing shell dotfiles."""
+
+    cli_context: CliContext = context.obj
+    try:
+        config_path = initialize_config(cli_context.config_path)
+    except FileExistsError:
+        typer.echo(
+            f"configuration already exists: {cli_context.config_path.expanduser()}",
+            err=True,
+        )
+        raise typer.Exit(1) from None
+    except OSError as error:
+        typer.echo(f"error: cannot create configuration: {error}", err=True)
+        raise typer.Exit(1) from error
+
+    typer.echo(f"created configuration: {config_path}")
+    typer.echo("no shell startup files were modified")

lab_env/cli/cmd_remote.py

@@ -0,0 +1,113 @@
+"""Connect to configured hosts and transfer files."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from lab_env.cli.context import CliContext
+from lab_env.config import ConfigError, HostConfig, load_config
+from lab_env.remote import (
+    RemoteCommandError,
+    build_connect_command,
+    build_transfer_command,
+    format_command,
+    resolve_host,
+    run_command,
+)
+
+
+def _load_cli_host(context: typer.Context, host_name: str) -> HostConfig:
+    """Load one host or convert configuration errors to CLI failures."""
+
+    cli_context: CliContext = context.obj
+    try:
+        config = load_config(cli_context.config_path)
+        return resolve_host(config, host_name)
+    except (ConfigError, RemoteCommandError) as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(2) from error
+
+
+def _execute(arguments: list[str], dry_run: bool) -> None:
+    """Run one command and preserve its process exit status."""
+
+    if dry_run:
+        typer.echo(format_command(arguments))
+        return
+
+    try:
+        result = run_command(arguments)
+    except RemoteCommandError as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from error
+
+    if result.return_code:
+        raise typer.Exit(result.return_code)
+
+
+def cmd_connect(
+    context: typer.Context,
+    host_name: Annotated[str, typer.Argument(help="Configured host name.")],
+    remote_args: Annotated[
+        list[str] | None,
+        typer.Argument(help="Optional command and arguments to run remotely."),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Print the SSH command without running it."),
+    ] = False,
+) -> None:
+    """Open SSH or run a command on a configured host."""
+
+    host = _load_cli_host(context, host_name)
+    arguments = build_connect_command(host, remote_args or ())
+    _execute(arguments, dry_run)
+
+
+def cmd_pull(
+    context: typer.Context,
+    host_name: Annotated[str, typer.Argument(help="Configured host name.")],
+    remote_path: Annotated[str, typer.Argument(help="Remote source path.")],
+    local_path: Annotated[
+        str,
+        typer.Argument(help="Local destination path."),
+    ] = ".",
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Print the rsync command without running it."),
+    ] = False,
+) -> None:
+    """Pull files from a configured host with resumable rsync."""
+
+    host = _load_cli_host(context, host_name)
+    arguments = build_transfer_command(
+        "pull",
+        host,
+        remote_path,
+        local_path,
+    )
+    _execute(arguments, dry_run)
+
+
+def cmd_push(
+    context: typer.Context,
+    host_name: Annotated[str, typer.Argument(help="Configured host name.")],
+    local_path: Annotated[str, typer.Argument(help="Local source path.")],
+    remote_path: Annotated[str, typer.Argument(help="Remote destination path.")],
+    dry_run: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Print the rsync command without running it."),
+    ] = False,
+) -> None:
+    """Push files to a configured host with resumable rsync."""
+
+    host = _load_cli_host(context, host_name)
+    arguments = build_transfer_command(
+        "push",
+        host,
+        local_path,
+        remote_path,
+    )
+    _execute(arguments, dry_run)

lab_env/cli/cmd_shell.py

@@ -0,0 +1,168 @@
+"""Preview and manage lab-env shell startup integration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from lab_env.cli.context import CliContext
+from lab_env.config import ConfigError, load_config
+from lab_env.shell import (
+    ShellIntegrationError,
+    ShellPaths,
+    install_shell,
+    integration_status,
+    render_generated_shell,
+    render_managed_block,
+    resolve_shell_paths,
+    uninstall_shell,
+)
+
+shell_app = typer.Typer(
+    help="Preview and manage shell startup integration.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _resolve_cli_shell_paths(
+    context: typer.Context,
+    shell_name: str | None,
+    rc_path: Path | None,
+) -> ShellPaths:
+    """Resolve shell paths or convert validation errors to CLI failures."""
+
+    cli_context: CliContext = context.obj
+    try:
+        return resolve_shell_paths(
+            cli_context.config_path,
+            shell=shell_name,
+            rc_path=rc_path,
+        )
+    except ShellIntegrationError as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(2) from error
+
+
+@shell_app.command("preview")
+def shell_preview_command(
+    context: typer.Context,
+    shell_name: Annotated[
+        str | None,
+        typer.Option("--shell", help="Shell to configure: bash or zsh."),
+    ] = None,
+    rc_path: Annotated[
+        Path | None,
+        typer.Option("--rc", help="Override the shell startup file."),
+    ] = None,
+) -> None:
+    """Show generated files and dotfile changes without writing anything."""
+
+    cli_context: CliContext = context.obj
+    try:
+        load_config(cli_context.config_path)
+    except ConfigError as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(2) from error
+
+    paths = _resolve_cli_shell_paths(context, shell_name, rc_path)
+    typer.echo(f"shell: {paths.shell}")
+    typer.echo(f"startup file: {paths.rc_path}")
+    typer.echo(f"generated file: {paths.generated_path}")
+    typer.echo("\ngenerated shell file:\n")
+    typer.echo(render_generated_shell(cli_context.config_path), nl=False)
+    typer.echo("\nmanaged startup block:\n")
+    typer.echo(render_managed_block(paths.generated_path), nl=False)
+
+
+@shell_app.command("install")
+def shell_install_command(
+    context: typer.Context,
+    shell_name: Annotated[
+        str | None,
+        typer.Option("--shell", help="Shell to configure: bash or zsh."),
+    ] = None,
+    rc_path: Annotated[
+        Path | None,
+        typer.Option("--rc", help="Override the shell startup file."),
+    ] = None,
+) -> None:
+    """Install an idempotent managed block in the shell startup file."""
+
+    cli_context: CliContext = context.obj
+    try:
+        load_config(cli_context.config_path)
+        paths = resolve_shell_paths(
+            cli_context.config_path,
+            shell=shell_name,
+            rc_path=rc_path,
+        )
+        result = install_shell(paths, cli_context.config_path)
+    except (ConfigError, OSError, ShellIntegrationError) as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from error
+
+    if result.changed:
+        typer.echo(f"installed lab-env shell integration in {paths.rc_path}")
+        if result.backup_path is not None:
+            typer.echo(f"backup: {result.backup_path}")
+    else:
+        typer.echo(f"shell integration already installed: {paths.rc_path}")
+    typer.echo(f"generated: {paths.generated_path}")
+    typer.echo(f"activate now: source {paths.rc_path}")
+
+
+@shell_app.command("status")
+def shell_status_command(
+    context: typer.Context,
+    shell_name: Annotated[
+        str | None,
+        typer.Option("--shell", help="Shell to inspect: bash or zsh."),
+    ] = None,
+    rc_path: Annotated[
+        Path | None,
+        typer.Option("--rc", help="Override the shell startup file."),
+    ] = None,
+) -> None:
+    """Report whether shell integration is installed and complete."""
+
+    paths = _resolve_cli_shell_paths(context, shell_name, rc_path)
+    status = integration_status(paths)
+    typer.echo(f"{paths.shell}: {status}")
+    typer.echo(f"startup file: {paths.rc_path}")
+    typer.echo(f"generated file: {paths.generated_path}")
+    if status == "incomplete":
+        raise typer.Exit(1)
+
+
+@shell_app.command("uninstall")
+def shell_uninstall_command(
+    context: typer.Context,
+    shell_name: Annotated[
+        str | None,
+        typer.Option("--shell", help="Shell to configure: bash or zsh."),
+    ] = None,
+    rc_path: Annotated[
+        Path | None,
+        typer.Option("--rc", help="Override the shell startup file."),
+    ] = None,
+) -> None:
+    """Remove only lab-env-owned shell startup content."""
+
+    paths = _resolve_cli_shell_paths(context, shell_name, rc_path)
+    try:
+        previous_status = integration_status(paths)
+        backup_path = uninstall_shell(paths)
+    except (OSError, ShellIntegrationError) as error:
+        typer.echo(f"error: {error}", err=True)
+        raise typer.Exit(1) from error
+
+    if previous_status == "not installed":
+        typer.echo(f"shell integration is not installed: {paths.rc_path}")
+        return
+
+    typer.echo(f"removed lab-env shell integration from {paths.rc_path}")
+    if backup_path is not None:
+        typer.echo(f"backup: {backup_path}")

lab_env/cli/context.py

@@ -0,0 +1,13 @@
+"""Shared state for lab-env CLI commands."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class CliContext:
+    """Values shared by lab subcommands."""
+
+    config_path: Path

lab_env/config/__init__.py

@@ -0,0 +1,15 @@
+"""Public configuration API for lab-env."""
+
+from lab_env.config.classes import ConfigError, HostConfig, LabConfig, ShellConfig
+from lab_env.config.initialize import default_config_path, initialize_config
+from lab_env.config.load import load_config
+
+__all__ = [
+    "ConfigError",
+    "HostConfig",
+    "LabConfig",
+    "ShellConfig",
+    "default_config_path",
+    "initialize_config",
+    "load_config",
+]

lab_env/config/classes.py

@@ -0,0 +1,40 @@
+"""Configuration data classes and shared schema constants."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+SCHEMA_VERSION = 1
+
+
+class ConfigError(ValueError):
+    """Raised when personal configuration cannot be loaded or validated."""
+
+
+@dataclass(frozen=True, slots=True)
+class HostConfig:
+    """Connection metadata for one configured host."""
+
+    destination: str
+    description: str | None = None
+    ssh_command: str = "ssh"
+
+
+@dataclass(frozen=True, slots=True)
+class ShellConfig:
+    """Shell aliases generated by lab-env."""
+
+    initialize_conda: bool = True
+    conda_init_path: str | None = None
+    default_aliases: bool = True
+    disabled_aliases: tuple[str, ...] = ()
+    aliases: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class LabConfig:
+    """Validated personal lab-env configuration."""
+
+    schema_version: int = SCHEMA_VERSION
+    hosts: dict[str, HostConfig] = field(default_factory=dict)
+    shell: ShellConfig = field(default_factory=ShellConfig)

lab_env/config/initialize.py

@@ -0,0 +1,88 @@
+"""Configuration path resolution and initialization."""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+from lab_env.config.classes import SCHEMA_VERSION
+
+
+def default_config_path() -> Path:
+    """Return the platform-neutral user configuration path."""
+
+    configured_path = os.environ.get("LAB_ENV_CONFIG")
+    if configured_path:
+        return Path(configured_path).expanduser()
+
+    config_root = os.environ.get("XDG_CONFIG_HOME")
+    if config_root:
+        return Path(config_root).expanduser() / "lab-env" / "config.toml"
+    return Path.home() / ".config" / "lab-env" / "config.toml"
+
+
+def initialize_config(path: Path) -> Path:
+    """Create a default personal configuration without replacing existing data.
+
+    Args:
+        path: Destination configuration path.
+
+    Returns:
+        The resolved path written to disk.
+
+    Raises:
+        FileExistsError: If the destination already exists.
+        OSError: If the destination cannot be created.
+    """
+
+    resolved_path = path.expanduser()
+    resolved_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    created_at = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+    config_text = (
+        "# --------------------------------------------------\n"
+        "# lab-env user configuration\n"
+        f"# created at: {created_at}\n"
+        "# persistent user-owned file; make and keep your changes here\n"
+        "# lab init will never overwrite this file\n"
+        "# --------------------------------------------------\n\n"
+        "# --------------------------------------------------\n"
+        "# basic settings: config format used by lab-env\n"
+        "# --------------------------------------------------\n"
+        "# Do not change this value manually.\n"
+        f"schema_version = {SCHEMA_VERSION}\n\n"
+        "# --------------------------------------------------\n"
+        "# shell configuration: controls generated shell integration\n"
+        "# --------------------------------------------------\n"
+        "[shell]\n"
+        "# Make conda activate available for common Miniforge/Miniconda installations.\n"
+        "initialize_conda = true\n"
+        "# Optional explicit path for custom or module-provided Conda installations.\n"
+        '# conda_init_path = "/path/to/etc/profile.d/conda.sh"\n'
+        "# Generate the standard aliases defined by lab-env.\n"
+        "default_aliases = true\n"
+        '# Skip selected defaults, for example: ["rm", "cp"].\n'
+        "disabled_aliases = []\n\n"
+        "# --------------------------------------------------\n"
+        "# user-defined aliases: persistent commands and default overrides\n"
+        "# --------------------------------------------------\n"
+        "[shell.aliases]\n"
+        '# gs = "git status"\n'
+        "# work = 'cd \"$HOME/work\"'\n"
+        '# ll = "eza --long --header"\n\n'
+        "# --------------------------------------------------\n"
+        "# remote hosts: named systems used by connect, pull, and push\n"
+        "# --------------------------------------------------\n"
+        "# Define each as [hosts.NAME]; authentication remains in ~/.ssh/config.\n"
+        "[hosts]\n\n"
+        "# Example named host and its available fields:\n"
+        "# [hosts.cluster]\n"
+        '# destination = "user@cluster.example.edu"\n'
+        '# description = "Research cluster"\n'
+        '# ssh_command = "ssh"\n'
+    )
+
+    with resolved_path.open("x", encoding="utf-8") as stream:
+        stream.write(config_text)
+
+    return resolved_path.resolve()