lumilake-cli 0.1.0.dev1__py3-none-any.whl

lumilake_cli/cli.py

@@ -0,0 +1,54 @@
+"""Lumilake CLI entrypoint.
+
+Installs a typer-aware handler on the shared ``Lumilake`` logger root so
+records from every workspace package render with the CLI colour palette.
+"""
+
+import logging
+
+import typer
+from lumilake.log import ColorFormatter, get_default_logger
+
+from .commands import register
+from .core.typer import get_typer
+
+root_app = get_typer(help="Lumilake command line interface.")
+
+
+class _TyperHandler(logging.Handler):
+    """Routes records through ``typer.echo``: stdout for INFO/DEBUG,
+    stderr for WARNING/ERROR/CRITICAL. Honours typer's color detection.
+    Coloring is left to ``ColorFormatter``.
+    """
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            message = self.format(record)
+        except Exception:
+            self.handleError(record)
+            return
+        typer.echo(message, err=record.levelno >= logging.WARNING)
+
+
+def _install_handler() -> None:
+    root = get_default_logger()
+    if any(isinstance(h, _TyperHandler) for h in root.handlers):
+        return
+    # Drop get_default_logger's StreamHandler so records aren't doubled.
+    for existing in list(root.handlers):
+        root.removeHandler(existing)
+    handler = _TyperHandler()
+    handler.setFormatter(ColorFormatter())
+    root.addHandler(handler)
+    root.propagate = False
+
+
+def main() -> None:
+    """Attach command groups and dispatch to Typer."""
+    _install_handler()
+    register(root_app)
+    root_app()
+
+
+if __name__ == "__main__":
+    main()

lumilake_cli/commands/__init__.py

@@ -0,0 +1,69 @@
+"""Command modules for the Lumilake CLI."""
+
+from importlib.util import find_spec
+
+import typer
+
+from .base import app as base_app
+from .job import app as job_app
+from .trace import app as trace_app
+from .worker import app as worker_app
+
+# The ``[deploy]`` extra pulls ``lumilake-deploy`` and
+# ``flowmesh-cli-stack``; gate on both up front so real ImportError
+# from inside .deploy still bubbles up loudly.
+_DEPLOY_AVAILABLE = (
+    find_spec("lumilake_deploy") is not None
+    and find_spec("flowmesh_cli_stack") is not None
+)
+
+if _DEPLOY_AVAILABLE:
+    from .deploy import app as deploy_app
+else:
+    _DEPLOY_INSTALL_HINT = (
+        "lumilake deploy requires the `deploy` extra. Install with "
+        "`pip install 'lumilake[cli]'` or "
+        "`pip install 'lumilake-cli[deploy]'`."
+    )
+    deploy_app = typer.Typer(
+        help=(
+            "Deploy and manage the Lumilake stack. Install with "
+            "`pip install 'lumilake[cli]'` or "
+            "`pip install 'lumilake-cli[deploy]'` to enable."
+        )
+    )
+
+    def _deploy_hint() -> None:
+        typer.echo(_DEPLOY_INSTALL_HINT, err=True)
+        raise typer.Exit(code=2)
+
+    @deploy_app.callback(invoke_without_command=True)
+    def _deploy_no_subcommand(ctx: typer.Context) -> None:
+        if ctx.resilient_parsing or ctx.invoked_subcommand is not None:
+            return
+        _deploy_hint()
+
+    for _name in (
+        "init",
+        "doctor",
+        "build",
+        "pull",
+        "up",
+        "down",
+        "clean",
+        "reset",
+        "status",
+        "restart",
+        "logs",
+        "update-flowmesh",
+    ):
+        deploy_app.command(_name)(_deploy_hint)
+
+
+def register(app: typer.Typer) -> None:
+    """Register command groups on the root app."""
+    app.add_typer(base_app)
+    app.add_typer(deploy_app, name="deploy")
+    app.add_typer(job_app, name="job")
+    app.add_typer(worker_app, name="worker")
+    app.add_typer(trace_app, name="trace")

lumilake_cli/commands/base.py

@@ -0,0 +1,85 @@
+import json
+from pathlib import Path
+
+import typer
+
+from ..core import logging
+from ..core.config import DEFAULT_CONFIG_PATH, LumilakeConfig, save_config
+from ..core.http import HttpClient, HttpError, client_from_config
+from ..core.typer import get_typer
+
+app = get_typer()
+
+
+@app.command()
+def login(
+    url: str = typer.Argument(
+        ..., help="Lumilake server URL (e.g., http://localhost:9000)"
+    ),
+    config_path: Path = typer.Option(
+        DEFAULT_CONFIG_PATH, "--config", help="Path to save configuration file"
+    ),
+) -> None:
+    """Configure connection to a Lumilake server and save it locally."""
+    client = HttpClient(base_url=url)
+    try:
+        client.get("/healthz")
+    except HttpError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1)
+    save_config(LumilakeConfig(base_url=url), path=config_path)
+    logging.success(f"Login successful. Saved config to {config_path}")
+
+
+@app.command()
+def logout(
+    config_path: Path = typer.Option(
+        DEFAULT_CONFIG_PATH, "--config", help="Path to configuration file to remove"
+    ),
+) -> None:
+    """Delete saved configuration."""
+    config_path.unlink(missing_ok=True)
+    logging.success(f"Logout successful. Removed config {config_path}")
+
+
+@app.command()
+def config(
+    refresh: bool = typer.Option(
+        False, "--refresh", "-r", help="Reload and show the latest configuration"
+    ),
+    config_path: Path = typer.Option(
+        DEFAULT_CONFIG_PATH, "--config", help="Path to configuration file"
+    ),
+) -> None:
+    """Show the current Lumilake CLI configuration."""
+    from ..core.http import _require_config
+
+    cfg = _require_config(config_path)
+    if refresh:
+        client = HttpClient(base_url=cfg.base_url)
+        try:
+            client.get("/healthz")
+        except HttpError as exc:
+            logging.error(str(exc))
+            raise typer.Exit(code=1)
+        save_config(cfg, path=config_path)
+        logging.success(f"Configuration refreshed. Saved to {config_path}")
+    logging.log(json.dumps(cfg.to_mapping(), indent=2))
+
+
+@app.command()
+def info() -> None:
+    """Query server health status."""
+    client = client_from_config()
+    try:
+        response = client.get("/healthz")
+    except HttpError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1)
+    logging.log(json.dumps(response.json(), indent=2))
+
+
+@app.command()
+def health() -> None:
+    """Check if the Lumilake server is reachable and healthy."""
+    info()

lumilake_cli/commands/deploy.py

@@ -0,0 +1,462 @@
+"""Deploy commands: init, doctor, up, down, clean, restart, reset, logs."""
+
+import datetime as dt
+import re
+import sys
+from pathlib import Path
+
+import typer
+from flowmesh_cli_stack.stack import stack_env_example
+from lumilake_deploy import docker_client
+from lumilake_deploy import setup as setup_mod
+from lumilake_deploy import stop as stop_mod
+from lumilake_deploy import update_flowmesh as update_fm_mod
+from lumilake_deploy.assets import env_example_path
+from lumilake_deploy.containers import SERVICE_NAMES, container_names
+from lumilake_deploy.doctor import DoctorFinding, run_doctor
+from lumilake_deploy.env import (
+    ENV_FILE_NAME,
+    FLOWMESH_ENV_FILE_NAME,
+    patch_env_value,
+)
+from lumilake_deploy.errors import DeployError
+from lumilake_deploy.setup import (
+    SetupOptions,
+    build_server_image,
+    pull_server_image,
+)
+
+from ..core import logging
+from ..core.typer import get_typer
+
+app = get_typer(
+    help=(
+        "Deploy and manage the Lumilake stack. Reads .env (and optionally "
+        ".env.flowmesh) from --project-dir (or the current working "
+        "directory). The packaged compose file and server image are "
+        "resolved from the installed lumilake-deploy package."
+    )
+)
+
+
+@app.callback()
+def _deploy_callback(
+    ctx: typer.Context,
+    project_dir: Path = typer.Option(
+        None,
+        "--project-dir",
+        "-C",
+        envvar="LUMILAKE_DEPLOY_DIR",
+        help=(
+            "Directory holding .env / .env.flowmesh and where compose "
+            "stores runtime state. Defaults to the current working directory."
+        ),
+    ),
+) -> None:
+    ctx.obj = project_dir.resolve() if project_dir else Path.cwd()
+
+
+def _project_dir(ctx: typer.Context) -> Path:
+    if isinstance(ctx.obj, Path):
+        return ctx.obj
+    return Path.cwd()
+
+
+def _run_setup(
+    root: Path,
+    *,
+    background: bool = True,
+    reset: bool = False,
+    no_server: bool = False,
+) -> None:
+    try:
+        setup_mod.run_setup(
+            root,
+            SetupOptions(
+                reset=reset,
+                no_server=no_server,
+                background=background,
+            ),
+        )
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+def _confirm_overwrite(target: Path, *, force: bool) -> bool:
+    """Return True when the target may be written, False to skip."""
+    if not target.exists() or force:
+        return True
+    if typer.confirm(f"{target} already exists. Overwrite?", default=False):
+        return True
+    logging.info(f"Keeping existing {target}.")
+    return False
+
+
+def _flowmesh_env_value(env_path: Path, key: str) -> str:
+    """Read a single line from ``.env.flowmesh`` (no quoting strip pattern)."""
+    if not env_path.is_file():
+        return ""
+    prefix = f"{key}="
+    for raw in env_path.read_text().splitlines():
+        line = raw.strip()
+        if not line.startswith(prefix):
+            continue
+        value = line[len(prefix) :]
+        if value.startswith('"') and value.endswith('"'):
+            value = value[1:-1]
+        return value
+    return ""
+
+
+_FLOWMESH_LOCAL_OVERRIDES: tuple[tuple[str, str], ...] = (
+    ("FLOWMESH_STACK_SUFFIX", "lumilake"),
+    ("SERVER_GRPC_TLS_CA_FILE", ""),
+    ("SERVER_GRPC_TLS_CERT_FILE", ""),
+    ("SERVER_GRPC_TLS_KEY_FILE", ""),
+    ("REDIS_TLS_CA_FILE", ""),
+    ("REDIS_TLS_CERT_FILE", ""),
+    ("REDIS_TLS_KEY_FILE", ""),
+)
+
+
+def _patch_flowmesh_env(env_path: Path) -> None:
+    """Disable TLS bind mounts on the bundled FlowMesh template."""
+    for key, value in _FLOWMESH_LOCAL_OVERRIDES:
+        patch_env_value(env_path, key, value)
+
+
+def _cross_populate_runtime(env_path: Path, fm_env_path: Path) -> None:
+    """After ``init --flowmesh`` writes both files, point ``.env``'s
+    ``LUMILAKE_RUNTIME_ORCHESTRATOR_URL`` at the FlowMesh server's port."""
+    server_port = _flowmesh_env_value(fm_env_path, "SERVER_HTTP_PORT") or "18000"
+    patch_env_value(
+        env_path,
+        "LUMILAKE_RUNTIME_ORCHESTRATOR_URL",
+        f"http://127.0.0.1:{server_port}",
+    )
+
+
+@app.command("init")
+def init(
+    ctx: typer.Context,
+    flowmesh: bool = typer.Option(
+        False,
+        "--flowmesh",
+        help="Also generate ``.env.flowmesh`` from FlowMesh's stack template.",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Overwrite existing env files without prompting.",
+    ),
+) -> None:
+    """Initialize ``.env`` from the bundled ``.env.example`` template."""
+    root = _project_dir(ctx)
+    template = env_example_path()
+    target = root / ENV_FILE_NAME
+    wrote_env = False
+    if _confirm_overwrite(target, force=force):
+        target.write_text(template.read_text())
+        logging.success(f"Wrote {target} from packaged {template.name}.")
+        wrote_env = True
+
+    if flowmesh:
+        fm_target = root / FLOWMESH_ENV_FILE_NAME
+        wrote_flowmesh_env = False
+        if _confirm_overwrite(fm_target, force=force):
+            example = stack_env_example()
+            if not example.exists():
+                logging.error(f"FlowMesh env example not found: {example}")
+                raise typer.Exit(code=1)
+            fm_target.write_text(example.read_text())
+            logging.success(f"Wrote {fm_target} from {example.name}.")
+            _patch_flowmesh_env(fm_target)
+            wrote_flowmesh_env = True
+        if wrote_env:
+            _cross_populate_runtime(target, fm_target)
+        elif wrote_flowmesh_env:
+            logging.info(
+                f"Keeping existing {target}; not patching runtime URL from "
+                f"{fm_target}."
+            )
+
+
+@app.command()
+def doctor(
+    ctx: typer.Context,
+    flowmesh: bool = typer.Option(
+        False,
+        "--flowmesh",
+        help="Also validate that ``.env.flowmesh`` is present.",
+    ),
+) -> None:
+    """Validate ``.env`` (and optionally ``.env.flowmesh``)."""
+    root = _project_dir(ctx)
+
+    def _emit(finding: DoctorFinding) -> None:
+        if finding.level == "error":
+            logging.error(finding.message)
+        elif finding.level == "warning":
+            logging.warning(finding.message)
+        else:
+            logging.info(finding.message)
+
+    report = run_doctor(
+        root / ENV_FILE_NAME,
+        flowmesh_env_path=(root / FLOWMESH_ENV_FILE_NAME) if flowmesh else None,
+        callback=_emit,
+    )
+    if report.errors:
+        logging.error(f"Doctor found {len(report.errors)} issue(s).")
+        raise typer.Exit(code=1)
+    logging.success("Doctor checks passed.")
+
+
+@app.command()
+def build(ctx: typer.Context) -> None:
+    """Build the lumilake server Docker image from source."""
+    root = _project_dir(ctx)
+    setup_mod.load_project_env(root)
+    image_tag = setup_mod.resolve_image_tag()
+    try:
+        build_server_image(root, image_tag)
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def pull(ctx: typer.Context) -> None:
+    """Pull the published lumilake server image from the registry."""
+    root = _project_dir(ctx)
+    setup_mod.load_project_env(root)
+    image_tag = setup_mod.resolve_image_tag()
+    try:
+        pull_server_image(image_tag)
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def up(ctx: typer.Context) -> None:
+    """Start the full Lumilake stack (Docker-backed).
+
+    The server image must already be present locally — run
+    ``lumilake deploy pull`` or ``lumilake deploy build`` first.
+    """
+    _run_setup(_project_dir(ctx), background=True)
+
+
+@app.command()
+def down(
+    ctx: typer.Context,
+    wipe_archive: bool = typer.Option(
+        False,
+        "--wipe-archive",
+        help=(
+            "Also wipe runtime state that accumulates across "
+            "deploy cycles (FlowMesh postgres + redis). "
+            "Fixes the 'Duplicate key' / silent-retry-loop failure mode "
+            "after a killed prior run. Use this between experiment runs "
+            "if you don't want a full "
+            "``deploy reset`` + re-stage."
+        ),
+    ),
+) -> None:
+    """Stop all services (keep data)."""
+    try:
+        stop_mod.run_stop(
+            _project_dir(ctx),
+            purge=False,
+            wipe_archive=wipe_archive,
+        )
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def clean(ctx: typer.Context) -> None:
+    """Stop all services and delete volumes."""
+    try:
+        stop_mod.run_stop(_project_dir(ctx), purge=True)
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+
+
+@app.command()
+def status(ctx: typer.Context) -> None:
+    """Show the running state of every Lumilake stack container."""
+    rows: list[tuple[str, str, str, str]] = []
+    for service, container in container_names(_project_dir(ctx)).items():
+        state = docker_client.container_status(container)
+        health = (
+            docker_client.container_health_status(container)
+            if state == "running"
+            else ""
+        )
+        rows.append((service, container, state, health))
+
+    svc_w = max(len(r[0]) for r in rows)
+    cnt_w = max(len(r[1]) for r in rows)
+    state_w = max(len(r[2]) for r in rows)
+    for service, container, state, health in rows:
+        line = f"{service:<{svc_w}}  {container:<{cnt_w}}  {state:<{state_w}}"
+        if health:
+            line += f"  ({health})"
+        logging.info(line)
+
+
+@app.command()
+def restart(
+    ctx: typer.Context,
+    service: str | None = typer.Argument(
+        None,
+        help=(
+            "Single service to restart. Choose from: "
+            f"{', '.join(SERVICE_NAMES)}. When omitted, restarts the "
+            "entire stack (re-runs setup, rebuilds images)."
+        ),
+    ),
+) -> None:
+    """Restart deployment services.
+
+    Without ``service``: stops the entire stack and re-runs setup
+    (rebuilds images if code changed). With ``service``: restarts just
+    that container in place.
+    """
+    root = _project_dir(ctx)
+    if service is not None:
+        container = container_names(root).get(service)
+        if container is None:
+            logging.error(
+                f"Unknown service '{service}'. "
+                f"Choose from: {', '.join(SERVICE_NAMES)}"
+            )
+            raise typer.Exit(code=1)
+        try:
+            docker_client.container_restart(container)
+        except DeployError as exc:
+            logging.error(str(exc))
+            raise typer.Exit(code=1) from exc
+        return
+
+    try:
+        stop_mod.run_stop(root, purge=False)
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+    _run_setup(root, background=True)
+
+
+@app.command()
+def reset(ctx: typer.Context) -> None:
+    """Clean reset (stop + purge + up; deletes all data)."""
+    root = _project_dir(ctx)
+    try:
+        stop_mod.run_stop(root, purge=True)
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+    _run_setup(root, background=True, reset=True)
+
+
+_SINCE_RE = re.compile(r"^(\d+)([smhd])$")
+
+
+def _parse_since(value: str | None) -> dt.datetime | None:
+    """Parse ``10m`` / ``2h`` / ``1d`` / ``30s`` into a past ``datetime``.
+
+    Returns ``None`` when ``value`` is ``None``. Exits the CLI on an
+    unparsable value.
+    """
+    if value is None:
+        return None
+    match = _SINCE_RE.match(value.strip())
+    if not match:
+        logging.error(
+            f"--since must be one of <N>s/m/h/d (e.g. 30s, 10m, 2h, 1d); got {value!r}"
+        )
+        raise typer.Exit(code=1)
+    amount = int(match.group(1))
+    unit = match.group(2)
+    delta = {
+        "s": dt.timedelta(seconds=amount),
+        "m": dt.timedelta(minutes=amount),
+        "h": dt.timedelta(hours=amount),
+        "d": dt.timedelta(days=amount),
+    }[unit]
+    return dt.datetime.now(dt.UTC) - delta
+
+
+@app.command()
+def logs(
+    ctx: typer.Context,
+    service: str = typer.Argument(
+        "server",
+        help=f"Service name: {', '.join(SERVICE_NAMES)}",
+    ),
+    tail: int | None = typer.Option(
+        None, "--tail", "-n", help="Show last N lines and exit (default: follow live)."
+    ),
+    since: str | None = typer.Option(
+        None,
+        "--since",
+        help=(
+            "Only show logs newer than this duration: "
+            "<N>s, <N>m, <N>h, <N>d (e.g. 30s, 10m, 2h, 1d)."
+        ),
+    ),
+    timestamps: bool = typer.Option(
+        False,
+        "--timestamps",
+        "-t",
+        help="Prepend an RFC3339 timestamp to each log line.",
+    ),
+) -> None:
+    """Show logs for a Lumilake service.
+
+    Follows by default; use ``-n`` to show the last N lines and exit.
+    ``--since`` filters to entries newer than the given relative duration.
+    """
+    container = container_names(_project_dir(ctx)).get(service)
+    if container is None:
+        logging.error(
+            f"Unknown service '{service}'. Choose from: {', '.join(SERVICE_NAMES)}"
+        )
+        raise typer.Exit(code=1)
+    since_dt = _parse_since(since)
+    try:
+        if tail is not None:
+            output = docker_client.container_logs_tail(
+                container, tail=tail, since=since_dt, timestamps=timestamps
+            )
+            sys.stdout.write(output)
+            if output and not output.endswith("\n"):
+                sys.stdout.write("\n")
+            sys.stdout.flush()
+        else:
+            for chunk in docker_client.container_logs_stream(
+                container, since=since_dt, timestamps=timestamps
+            ):
+                sys.stdout.buffer.write(chunk)
+                sys.stdout.buffer.flush()
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc
+    except KeyboardInterrupt:
+        return
+
+
+@app.command("update-flowmesh")
+def update_flowmesh_cmd(ctx: typer.Context) -> None:
+    """Re-lock and install the latest FlowMesh packages."""
+    try:
+        update_fm_mod.run_update(_project_dir(ctx))
+    except DeployError as exc:
+        logging.error(str(exc))
+        raise typer.Exit(code=1) from exc