lablink-cli 0.1.0__py3-none-any.whl

lablink_cli/commands/reset_overlay.py

@@ -0,0 +1,109 @@
+"""`lablink client reset-overlay` — discard this box's persisted overlay
+node identity.
+
+Separate from `unregister` on purpose. `unregister` keeps the identity so
+that unregister/register lands back on the same tailnet node with the same
+MagicDNS name. Removing it is the opposite intent — "let this box join as a
+brand-new node next time" — and it has a consequence that has to be stated
+out loud rather than buried in a teardown path:
+
+Deleting the local state does NOT delete the machine from the tailnet. The
+coordination server keeps its own record, the machine simply goes offline,
+and it *keeps holding its MagicDNS name*. So the next `register` mints a new
+node which cannot claim that name and is handed a suffixed one
+(`...-gpu-1` -> `...-gpu-1-1`). Freeing the name requires deleting the stale
+node in the Tailscale admin console. This command therefore says so.
+
+The client reports whatever name it actually got back to the allocator (see
+client/start.sh), so a suffixed name is not broken — just untidy, and
+untidiness here is what made lablink#404 hard to read.
+"""
+
+from __future__ import annotations
+
+import typer
+from rich.console import Console
+
+from lablink_cli.commands.register import TAILSCALE_STATE_VOLUME
+from lablink_cli.docker import Docker, DockerUnavailable, default_docker
+from lablink_cli.log_shipper import CONTAINER_NAME
+
+TAILNET_ADMIN_URL = "https://login.tailscale.com/admin/machines"
+
+
+def run_reset_overlay(*, yes: bool, docker: Docker | None = None) -> None:
+    """Remove the persisted tailscaled state volume for the BYO client."""
+    docker = docker or default_docker()
+    console = Console()
+
+    try:
+        docker.require()
+    except DockerUnavailable:
+        console.print(
+            "[red]docker is not on PATH.[/red] There is nothing for this "
+            "command to remove without it."
+        )
+        raise SystemExit(1)
+
+    status = docker.container_status(CONTAINER_NAME)
+    if status == "daemon_error":
+        console.print(
+            "[red]Docker daemon is unreachable.[/red] Start Docker and "
+            "re-run."
+        )
+        raise SystemExit(1)
+    if status != "missing":
+        # Docker refuses to remove a volume that is still attached, and
+        # tearing the container down belongs to unregister — don't duplicate
+        # it here and half-succeed.
+        console.print(
+            f"[red]The {CONTAINER_NAME} container still exists "
+            f"(status: {status}).[/red]\n"
+            "Docker will not remove a volume that is still attached. Run "
+            "[bold]lablink client unregister[/bold] first (or "
+            f"`docker rm -f {CONTAINER_NAME}`), then re-run this command."
+        )
+        raise SystemExit(1)
+
+    if not docker.volume_exists(TAILSCALE_STATE_VOLUME):
+        console.print(
+            "Nothing to reset — no persisted overlay identity on this box."
+        )
+        return
+
+    if not yes:
+        confirmed = typer.confirm(
+            f"Remove the {TAILSCALE_STATE_VOLUME} volume? The next "
+            "`lablink client register` will join the tailnet as a new node.",
+            default=False,
+        )
+        if not confirmed:
+            console.print("Aborted.")
+            return
+
+    result = docker.remove_volume(TAILSCALE_STATE_VOLUME)
+    if not result.ok:
+        console.print(
+            f"[red]Could not remove {TAILSCALE_STATE_VOLUME}: "
+            f"{result.stderr.strip() or '(no stderr)'}[/red]"
+        )
+        raise SystemExit(1)
+
+    console.print(
+        f"[green]Removed {TAILSCALE_STATE_VOLUME}.[/green] The next "
+        "`lablink client register` will join the tailnet as a new node."
+    )
+    # Said explicitly because it is the non-obvious half: the operator has
+    # just discarded the local identity, but the old machine is still in the
+    # tailnet holding the name, so the new node gets a numeric suffix until
+    # that machine is deleted. Silence here is what makes the suffix look
+    # like a typo rather than a rename (lablink#404).
+    console.print(
+        "\n[yellow]This does not remove the old machine from your "
+        "tailnet.[/yellow] It goes offline but keeps holding its MagicDNS "
+        "name, so the new node will be given a numeric suffix (e.g. "
+        "[dim]-gpu-1[/dim] -> [dim]-gpu-1-1[/dim]) until you delete the "
+        f"stale machine at:\n  {TAILNET_ADMIN_URL}\n"
+        "The client reports whichever name it actually receives, so a "
+        "suffixed name still works."
+    )

lablink_cli/commands/setup.py

@@ -0,0 +1,347 @@
+"""AWS bootstrapping for LabLink (S3, DynamoDB, Route53).
+
+Replaces the template repo's setup.sh with boto3 calls.
+Creates the infrastructure needed before `lablink deploy` can run.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import boto3
+from botocore.exceptions import ClientError
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from lablink_allocator_service.conf.structured_config import Config
+
+console = Console()
+
+
+def _get_session(region: str) -> boto3.Session:
+    """Create a boto3 session for the given region."""
+    return boto3.Session(region_name=region)
+
+
+# ------------------------------------------------------------------
+# Step 1: Validate AWS credentials
+# ------------------------------------------------------------------
+def check_credentials(session: boto3.Session) -> dict:
+    """Validate AWS credentials and return caller identity."""
+    sts = session.client("sts")
+    try:
+        identity = sts.get_caller_identity()
+        return {
+            "account": identity["Account"],
+            "arn": identity["Arn"],
+            "user_id": identity["UserId"],
+        }
+    except (ClientError, Exception) as e:
+        console.print(
+            "[red]AWS credentials not found or invalid.[/red]"
+        )
+        console.print()
+        console.print(
+            "  To create access keys, visit:"
+        )
+        console.print(
+            "  [link=https://console.aws.amazon.com/iam/"
+            "home#/security_credentials]"
+            "https://console.aws.amazon.com/iam/"
+            "home#/security_credentials"
+            "[/link]"
+        )
+        console.print()
+        console.print(
+            "  Then configure them with one of:"
+        )
+        console.print(
+            '  [dim]1. Run: [bold]aws configure[/bold]'
+            "[/dim]"
+        )
+        console.print(
+            "  [dim]2. Set environment variables: "
+            "[bold]AWS_ACCESS_KEY_ID[/bold] and "
+            "[bold]AWS_SECRET_ACCESS_KEY[/bold][/dim]"
+        )
+        console.print()
+        console.print(f"  [dim]Error: {e}[/dim]")
+        raise SystemExit(1)
+
+
+# ------------------------------------------------------------------
+# Step 2: Create S3 bucket for OpenTofu state
+# ------------------------------------------------------------------
+def create_s3_bucket(
+    session: boto3.Session, bucket_name: str, region: str
+) -> bool:
+    """Create an S3 bucket with versioning. Returns True if created."""
+    s3 = session.client("s3")
+
+    # Check if we already own this bucket
+    try:
+        s3.head_bucket(Bucket=bucket_name)
+        console.print(
+            f"  [green]exists[/green] S3 bucket: {bucket_name}"
+        )
+        return False
+    except ClientError:
+        # head_bucket returns 403 for both "not yours" and
+        # "doesn't exist" (S3 anti-enumeration behavior).
+        # Try create_bucket and handle specific errors instead.
+        pass
+
+    # Create bucket (us-east-1 doesn't use LocationConstraint)
+    create_args: dict = {"Bucket": bucket_name}
+    if region != "us-east-1":
+        create_args["CreateBucketConfiguration"] = {
+            "LocationConstraint": region
+        }
+
+    try:
+        s3.create_bucket(**create_args)
+    except ClientError as e:
+        code = e.response["Error"]["Code"]
+        if code == "BucketAlreadyOwnedByYou":
+            console.print(
+                f"  [green]exists[/green] S3 bucket: "
+                f"{bucket_name}"
+            )
+            return False
+        if code == "BucketAlreadyExists":
+            console.print(
+                f"  [red]error[/red] S3 bucket "
+                f"'{bucket_name}' is taken by another "
+                "account — this should not happen with "
+                "account-ID-based naming"
+            )
+            raise SystemExit(1)
+        raise
+
+    # Enable versioning
+    s3.put_bucket_versioning(
+        Bucket=bucket_name,
+        VersioningConfiguration={"Status": "Enabled"},
+    )
+    console.print(
+        f"  [green]created[/green] S3 bucket: {bucket_name} "
+        "(versioning enabled)"
+    )
+    return True
+
+
+# ------------------------------------------------------------------
+# Step 3: Create DynamoDB table for OpenTofu state locking
+# ------------------------------------------------------------------
+def create_dynamodb_table(
+    session: boto3.Session, region: str
+) -> bool:
+    """Create the lock-table DynamoDB table. Returns True if created."""
+    dynamodb = session.client("dynamodb", region_name=region)
+    table_name = "lock-table"
+
+    try:
+        dynamodb.describe_table(TableName=table_name)
+        console.print(
+            f"  [green]exists[/green] DynamoDB table: {table_name}"
+        )
+        return False
+    except dynamodb.exceptions.ResourceNotFoundException:
+        pass
+
+    dynamodb.create_table(
+        TableName=table_name,
+        KeySchema=[
+            {"AttributeName": "LockID", "KeyType": "HASH"},
+        ],
+        AttributeDefinitions=[
+            {"AttributeName": "LockID", "AttributeType": "S"},
+        ],
+        BillingMode="PAY_PER_REQUEST",
+    )
+
+    # Wait for table to become active
+    waiter = dynamodb.get_waiter("table_exists")
+    waiter.wait(
+        TableName=table_name,
+        WaiterConfig={"Delay": 2, "MaxAttempts": 30},
+    )
+    console.print(
+        f"  [green]created[/green] DynamoDB table: {table_name}"
+    )
+    return True
+
+
+# ------------------------------------------------------------------
+# Step 4: Route53 hosted zone (optional)
+# ------------------------------------------------------------------
+def create_route53_zone(
+    session: boto3.Session, domain: str
+) -> str | None:
+    """Create or find a Route53 hosted zone. Returns zone ID or None."""
+    route53 = session.client("route53")
+
+    # Extract root domain (e.g., example.com from test.example.com)
+    parts = domain.split(".")
+    if len(parts) >= 2:
+        zone_name = ".".join(parts[-2:])
+    else:
+        zone_name = domain
+
+    # Check for existing zone
+    resp = route53.list_hosted_zones_by_name(DNSName=zone_name)
+    matching = [
+        z
+        for z in resp["HostedZones"]
+        if z["Name"].rstrip(".") == zone_name
+    ]
+
+    if len(matching) == 1:
+        zone_id = matching[0]["Id"].replace("/hostedzone/", "")
+        console.print(
+            f"  [green]exists[/green] Route53 zone: "
+            f"{zone_name} ({zone_id})"
+        )
+        return zone_id
+
+    if len(matching) > 1:
+        console.print(
+            f"  [yellow]warning[/yellow] Multiple zones found "
+            f"for {zone_name} — resolve manually"
+        )
+        return None
+
+    # Create new zone
+    caller_ref = f"lablink-setup-{int(time.time())}"
+    resp = route53.create_hosted_zone(
+        Name=zone_name, CallerReference=caller_ref
+    )
+    zone_id = resp["HostedZone"]["Id"].replace(
+        "/hostedzone/", ""
+    )
+
+    # Show nameservers
+    zone_info = route53.get_hosted_zone(Id=zone_id)
+    nameservers = zone_info["DelegationSet"]["NameServers"]
+
+    console.print(
+        f"  [green]created[/green] Route53 zone: "
+        f"{zone_name} ({zone_id})"
+    )
+    console.print()
+    console.print(
+        Panel(
+            "\n".join(f"  {ns}" for ns in nameservers),
+            title="[yellow]Update your domain registrar "
+            "with these nameservers[/yellow]",
+            border_style="yellow",
+        )
+    )
+    return zone_id
+
+
+# ------------------------------------------------------------------
+# Main entry point
+# ------------------------------------------------------------------
+def resolve_bucket_name(account_id: str) -> str:
+    """Generate a unique bucket name using the AWS account ID."""
+    return f"lablink-tf-state-{account_id}"
+
+
+def run_setup(cfg: Config, config_path: Path | None = None) -> None:
+    """Run the full setup sequence.
+
+    No-ops for manual provider (no AWS remote-state resources needed).
+    """
+    if getattr(cfg, "provider", "aws") == "manual":
+        console.print(
+            "[yellow]Manual provider doesn't use S3/DynamoDB remote "
+            "state — skipping setup (no AWS resources will be "
+            "created).[/yellow]"
+        )
+        return
+
+    region = cfg.app.region
+
+    console.print()
+    console.print(
+        Panel(
+            "[bold]LabLink Setup — Remote State[/bold]\n"
+            "Creates S3 + DynamoDB for OpenTofu state.",
+            border_style="cyan",
+        )
+    )
+    console.print()
+
+    # Step 1: Credentials
+    console.print("[bold]Step 1/3:[/bold] Checking AWS credentials")
+    session = _get_session(region)
+    identity = check_credentials(session)
+    console.print(
+        f"  [green]authenticated[/green] "
+        f"Account: {identity['account']}, "
+        f"Identity: {identity['arn']}"
+    )
+    console.print()
+
+    # Resolve bucket name from account ID
+    bucket_name = resolve_bucket_name(identity["account"])
+
+    # Step 2: S3
+    console.print(
+        "[bold]Step 2/3:[/bold] S3 bucket for OpenTofu state"
+    )
+    create_s3_bucket(session, bucket_name, region)
+    console.print()
+
+    # Step 3: DynamoDB
+    console.print(
+        "[bold]Step 3/3:[/bold] DynamoDB table for state locking"
+    )
+    create_dynamodb_table(session, region)
+
+    # Persist bucket_name to user config
+    cfg.bucket_name = bucket_name
+    from lablink_cli.config.schema import save_config
+
+    if config_path is None:
+        from lablink_cli.app import DEFAULT_CONFIG
+
+        config_path = DEFAULT_CONFIG
+
+    save_config(cfg, config_path)
+    console.print(
+        f"  [green]saved[/green] bucket_name → {config_path}"
+    )
+    console.print()
+
+    # Optional: Route53
+    if cfg.dns.enabled and cfg.dns.terraform_managed:
+        console.print(
+            "[bold]Optional:[/bold] Route53 hosted zone"
+        )
+        zone_id = create_route53_zone(session, cfg.dns.domain)
+        if zone_id and not cfg.dns.zone_id:
+            cfg.dns.zone_id = zone_id
+            save_config(cfg, config_path)
+            console.print(
+                f"  [green]saved[/green] dns.zone_id → {config_path}"
+            )
+        console.print()
+
+    # Summary
+    summary = Table(title="Setup Complete", show_header=False)
+    summary.add_column("Resource", style="bold")
+    summary.add_column("Value")
+    summary.add_row("Region", region)
+    summary.add_row("S3 Bucket", bucket_name)
+    summary.add_row("DynamoDB Table", "lock-table")
+    summary.add_row("AWS Account", identity["account"])
+    console.print(summary)
+    console.print()
+    console.print(
+        "[dim]Next step:[/dim] "
+        "[bold]lablink deploy[/bold]"
+    )

lablink_cli/commands/stats.py

@@ -0,0 +1,133 @@
+"""Render a cohort session-metrics summary in the terminal.
+
+Numbers come from the allocator's /api/session-metrics/summary endpoint —
+the same view model the admin web UI consumes. This keeps `lablink stats`
+and /admin/session-metrics from ever showing different aggregates for
+the same deployment state.
+"""
+
+from __future__ import annotations
+
+from urllib.error import HTTPError, URLError
+
+from rich.console import Console
+from rich.table import Table
+
+from lablink_cli.api import authenticated_json_request
+from lablink_cli.commands.utils import (
+    get_allocator_url,
+    print_admin_credentials_hint,
+    resolve_admin_credentials,
+)
+
+console = Console()
+
+
+def _fetch(cfg) -> dict:
+    allocator_url = get_allocator_url(cfg)
+    if not allocator_url:
+        console.print("[red]Could not determine allocator URL.[/red]")
+        raise SystemExit(1)
+
+    admin_user, admin_pw = resolve_admin_credentials(cfg)
+
+    try:
+        return authenticated_json_request(
+            f"{allocator_url}/api/session-metrics/summary",
+            admin_user,
+            admin_pw,
+            ssl_provider=cfg.ssl.provider,
+        )
+    # HTTPError first: it subclasses URLError, and a rejected login is not
+    # an unreachable allocator — we reached it and it said no.
+    except HTTPError as e:
+        if e.code == 401:
+            console.print(
+                f"[red]The allocator rejected admin user "
+                f"'{admin_user}' (HTTP 401).[/red]"
+            )
+            print_admin_credentials_hint(cfg)
+        else:
+            console.print(f"[red]Could not reach allocator: {e}[/red]")
+        raise SystemExit(1) from e
+    except URLError as e:
+        console.print(f"[red]Could not reach allocator: {e}[/red]")
+        raise SystemExit(1) from e
+
+
+def _fmt_hms(seconds: int | float | None) -> str:
+    if seconds is None:
+        return "—"
+    s = int(seconds)
+    return f"{s // 3600:02d}:{(s % 3600) // 60:02d}:{s % 60:02d}"
+
+
+def run_stats(cfg) -> None:
+    body = _fetch(cfg)
+
+    if not body.get("enabled", False):
+        console.print(
+            "[yellow]Session metrics collection is disabled for this "
+            "deployment. Set monitoring.enabled: true in "
+            "~/.lablink/config.yaml to enable.[/yellow]"
+        )
+        return
+
+    summary = body.get("summary") or {}
+    label = body.get("subject_software_label") or "subject"
+    total = summary.get("total_vms", 0)
+
+    if total == 0:
+        console.print(
+            "[yellow]No session metrics yet. Either no VMs have "
+            "reported, or monitoring just started.[/yellow]"
+        )
+        return
+
+    deploy = getattr(cfg, "deployment_name", "lablink")
+    console.print(
+        f"\n[bold]LabLink session metrics — deploy \"{deploy}\" "
+        f"({total} VMs)[/bold]\n"
+    )
+
+    console.print("[bold]Funnel[/bold]")
+    funnel = summary.get("funnel", {})
+    funnel_total = total or 1
+    for stage_key, stage_label in (
+        ("started", "Started"),
+        ("labeled", "Labeled"),
+        ("trained", "Trained"),
+        ("tracked", "Tracked"),
+    ):
+        count = funnel.get(stage_key, 0)
+        pct = round(count / funnel_total * 100)
+        bar = "█" * (pct // 5)
+        console.print(
+            f"  {stage_label:<8} {count:>3} / {total:<3} {pct:>3}%  {bar}"
+        )
+
+    console.print("\n[bold]Summary[/bold]")
+    t = Table(show_header=False, box=None)
+    t.add_row(
+        "% reached training",
+        f"{summary.get('pct_reached_training', 0.0):.1f}%",
+    )
+    t.add_row(
+        f"Median time in {label}",
+        _fmt_hms(summary.get("median_seconds_in_subject_software")),
+    )
+    t.add_row(
+        "Median time-to-first-train",
+        _fmt_hms(summary.get("median_seconds_to_first_train")),
+    )
+    frames = summary.get("median_labeled_frames")
+    t.add_row(
+        "Median labeled frames",
+        str(frames) if frames is not None else "—",
+    )
+    epochs = summary.get("median_epochs_completed")
+    t.add_row(
+        "Median epochs completed",
+        str(epochs) if epochs is not None else "—",
+    )
+    console.print(t)