cupli 0.1.1__py3-none-any.whl

cupli/__init__.py

@@ -0,0 +1 @@
+"""Cupli — command-line orchestrator for multi-repository docker-compose workspaces."""

cupli/__main__.py

@@ -0,0 +1,6 @@
+"""Allows ``python -m cupli`` to invoke the CLI."""
+
+from cupli.manage import app
+
+if __name__ == "__main__":
+    app()

cupli/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI surface for cupli.
+
+Composed of small typer apps merged in :mod:`cupli.cli.root`. Each
+sub-module covers one area (workspace, lifecycle, exec, hooks, mounts,
+diagnostics) so that ``cupli --help`` can group commands and so that each
+team area lives in its own file.
+"""

cupli/cli/_completion.py

@@ -0,0 +1,157 @@
+"""Shell-completion callbacks shared across the typer surface.
+
+Every callback returns a list of candidate strings that ``startswith`` the
+incomplete token. Loading the space is best-effort — on any error the
+callback returns an empty list so completion never breaks the prompt.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cupli.core.loader import ResolvedSpace
+
+
+def _resolved_space_quiet() -> ResolvedSpace | None:
+    """Detect + load the effective space without ANY side effects.
+
+    Returns ``None`` on any error so completion stays silent.
+    """
+    from pathlib import Path
+
+    from cupli.core import registry
+    from cupli.core.loader import load_space
+
+    try:
+        detected = registry.detect_current_space(Path.cwd())
+        return load_space(detected.path, auto_register=False, auto_cache=False)
+    except Exception:
+        return None
+
+
+def complete_space_names(incomplete: str) -> list[str]:
+    """Complete every registered space name."""
+    from cupli.core import registry
+    from cupli.domain.errors import CupliError
+
+    try:
+        known = registry.list_known_spaces()
+    except CupliError:
+        return []
+    return [name for name in sorted(known) if name.startswith(incomplete)]
+
+
+def complete_shortcut_names(incomplete: str) -> list[str]:
+    """Complete every ``commands.<name>`` entry declared in the current space.
+
+    Reads from ``~/.cache/cupli/<space>/cache.json`` when available (fast
+    path); falls back to a fresh load when the cache is cold or stale.
+    """
+    from pathlib import Path
+
+    from cupli.core import cache, registry
+
+    try:
+        detected = registry.detect_current_space(Path.cwd())
+    except Exception:
+        return []
+    cached = cache.read_commands(detected.path)
+    if cached is not None:
+        return [name for name in sorted(cached.commands) if name.startswith(incomplete)]
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    return [name for name in sorted(resolved.space.commands) if name.startswith(incomplete)]
+
+
+def complete_service_names(incomplete: str) -> list[str]:
+    """Complete docker-compose service names (``apps[*].service`` or app key)."""
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    names = {app.primary_service_name(name) for name, app in resolved.space.apps.items()}
+    return sorted(name for name in names if name.startswith(incomplete))
+
+
+def complete_app_names(incomplete: str) -> list[str]:
+    """Complete app keys from the current space (for ``cupli with -c``)."""
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    return sorted(name for name in resolved.space.apps if name.startswith(incomplete))
+
+
+def complete_mount_names(incomplete: str) -> list[str]:
+    """Complete declared mount names (``mounts[*]``)."""
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    return sorted(name for name in resolved.space.mounts if name.startswith(incomplete))
+
+
+def complete_tag_names(incomplete: str) -> list[str]:
+    """Complete every tag declared across ``apps[*].tags``."""
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    tags: set[str] = set()
+    for app in resolved.space.apps.values():
+        tags.update(app.tags)
+    return sorted(tag for tag in tags if tag.startswith(incomplete))
+
+
+def complete_hook_scope(incomplete: str) -> list[str]:
+    """Complete the fixed ``--scope`` choices for the hooks command."""
+    return [scope for scope in ("all", "apps", "bases", "mounts") if scope.startswith(incomplete)]
+
+
+def complete_hook_targets(incomplete: str) -> list[str]:
+    """Complete target names across ``apps`` / ``bases`` / ``mounts``."""
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    names: set[str] = set()
+    names.update(resolved.space.apps)
+    names.update(resolved.space.bases)
+    names.update(resolved.space.mounts)
+    return sorted(name for name in names if name.startswith(incomplete))
+
+
+def complete_error_codes(incomplete: str) -> list[str]:
+    """Complete every known cupli error code (``E001`` … ``E0NN``)."""
+    from cupli.domain.errors import ERRORS
+
+    return sorted(code for code in ERRORS if code.startswith(incomplete.upper()))
+
+
+def complete_branch_map(incomplete: str) -> list[str]:
+    """Complete ``name=`` candidates for ``--map`` options on git checkout.
+
+    Returns the component name with a trailing ``=`` so the shell stops at the
+    point where the user has to type the branch.
+    """
+    if "=" in incomplete:
+        return []
+    resolved = _resolved_space_quiet()
+    if resolved is None:
+        return []
+    names: set[str] = set()
+    names.update(resolved.space.apps)
+    names.update(resolved.space.bases)
+    names.update(resolved.space.mounts)
+    return sorted(f"{name}=" for name in names if name.startswith(incomplete))
+
+
+__all__ = (
+    "complete_app_names",
+    "complete_branch_map",
+    "complete_error_codes",
+    "complete_hook_scope",
+    "complete_hook_targets",
+    "complete_mount_names",
+    "complete_service_names",
+    "complete_shortcut_names",
+    "complete_space_names",
+    "complete_tag_names",
+)

cupli/cli/container.py

@@ -0,0 +1,28 @@
+"""DI container carried on :attr:`typer.Context.obj`.
+
+Each typer command pulls dependencies out of the container instead of
+instantiating them inline. Services are added by later milestones — M3
+ships only the runtime context.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cupli.domain.runtime import RuntimeContext
+
+
+@dataclass
+class Container:
+    """Per-invocation DI container.
+
+    Attributes:
+        runtime: immutable :class:`RuntimeContext` for this invocation.
+    """
+
+    runtime: RuntimeContext | None = None
+
+
+__all__ = ("Container",)

cupli/cli/dashboard.py

@@ -0,0 +1,106 @@
+"""``cupli dashboard`` — minimal live status of workspace services.
+
+A small Rich ``Live`` display that polls ``docker compose ps`` on a 2-second
+cadence and re-renders the table. Press Ctrl-C to exit.
+
+Designed as a low-overhead first step toward the v2-plan §0 idea of a
+Textual TUI; if/when we adopt Textual, this command rebinds to the new app.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from typing import Annotated
+
+import typer
+from rich.live import Live
+from rich.table import Table
+
+from cupli.cli.workspace import _resolve_space_path, _strict_vars
+from cupli.core.loader import load_space
+from cupli.services.compose_service import build_argv, make_plan
+from cupli.utils.console import console
+from cupli.utils.exceptions import suppress_known_exceptions
+
+
+@suppress_known_exceptions
+def dashboard_command(
+    ctx: typer.Context,
+    interval: Annotated[float, typer.Option("--interval", "-i", help="Polling interval in seconds.")] = 2.0,
+) -> None:
+    """Live status table of workspace services (Ctrl-C to exit)."""
+    space_path = _resolve_space_path(ctx)
+    resolved = load_space(space_path, strict_vars=_strict_vars(ctx))
+    plan = make_plan(resolved)
+    argv = build_argv(plan, ["ps", "--format", "json", "-a"])
+
+    with Live(_blank_table(), console=console, refresh_per_second=4, transient=False) as live:
+        try:
+            while True:
+                live.update(_render_table(argv))
+                time.sleep(max(0.5, interval))
+        except KeyboardInterrupt:
+            pass
+
+
+def _render_table(argv: list[str]) -> Table:
+    """Run ``docker compose ps --format json`` and render the output as a table."""
+    rows = _read_rows(argv)
+    table = Table(title="Cupli dashboard (Ctrl-C to exit)", show_lines=False)
+    table.add_column("service", style="cyan", no_wrap=True)
+    table.add_column("state", style="white")
+    table.add_column("image", style="white")
+    table.add_column("ports", style="white")
+    if not rows:
+        table.add_row("(no services)", "—", "—", "—")
+        return table
+    for row in rows:
+        state = row.get("State", "?")
+        styled_state = f"[green]{state}[/green]" if state == "running" else f"[yellow]{state}[/yellow]"
+        table.add_row(
+            row.get("Service", row.get("Name", "?")),
+            styled_state,
+            row.get("Image", "?"),
+            row.get("Publishers") and str(row["Publishers"]) or "—",
+        )
+    return table
+
+
+def _blank_table() -> Table:
+    """Initial table shown before the first poll completes."""
+    table = Table(title="Cupli dashboard (warming up)")
+    table.add_column("status")
+    table.add_row("polling …")
+    return table
+
+
+def _read_rows(argv: list[str]) -> list[dict]:
+    """Parse the JSON output of ``docker compose ps --format json``."""
+    import json
+
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            check=False,
+            timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return []
+    if completed.returncode != 0:
+        return []
+    rows: list[dict] = []
+    for line in completed.stdout.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rows.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return rows
+
+
+__all__ = ("dashboard_command",)

cupli/cli/diagnostics.py

@@ -0,0 +1,74 @@
+"""``cupli graph`` / ``cupli stats`` — at-a-glance discovery commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from rich.tree import Tree
+
+from cupli.cli.workspace import _resolve_space_path, _strict_vars
+from cupli.core.loader import load_space
+from cupli.services.compose_service import build_env, make_plan
+from cupli.utils.console import console
+from cupli.utils.exceptions import suppress_known_exceptions
+from cupli.utils.subprocess import run_command
+
+
+@suppress_known_exceptions
+def graph_command(ctx: typer.Context) -> None:
+    """Print a tree of bases / apps + deps + mounts for the current space."""
+    space_path = _resolve_space_path(ctx)
+    resolved = load_space(space_path, strict_vars=_strict_vars(ctx))
+
+    root = Tree(f"[bold cyan]{resolved.space.name}[/bold cyan] [dim]({resolved.space_dir})[/dim]")
+    if resolved.space.bases:
+        bases_node = root.add("[bold]bases[/bold]")
+        for name in sorted(resolved.space.bases):
+            bases_node.add(f"[white]{name}[/white]")
+    apps_node = root.add("[bold]apps[/bold]")
+    for name in sorted(resolved.space.apps):
+        app = resolved.space.apps[name]
+        label = f"[white]{name}[/white]"
+        if app.tags:
+            label += f"  [dim]tags={','.join(app.tags)}[/dim]"
+        label += f"  [dim]mode={app.mode.value}[/dim]"
+        node = apps_node.add(label)
+        if app.bases:
+            node.add(f"[dim]bases: {', '.join(app.bases)}[/dim]")
+        if app.deps:
+            deps_str = ", ".join(f"{dep} [{','.join(m.value for m in modes)}]" for dep, modes in app.deps.items())
+            node.add(f"[yellow]deps:[/yellow] {deps_str}")
+    if resolved.space.mounts:
+        mounts_node = root.add("[bold]mounts[/bold]")
+        for name in sorted(resolved.space.mounts):
+            mount = resolved.space.mounts[name]
+            mounts_node.add(
+                f"[white]{name}[/white] -> [green]{', '.join(mount.hosted_in)}[/green]"
+                f"  [dim]exec_path={mount.exec_path}[/dim]",
+            )
+    if resolved.space.commands:
+        cmd_node = root.add("[bold]commands[/bold]")
+        for cmd_name in sorted(resolved.space.commands):
+            sc = resolved.space.commands[cmd_name]
+            cmd_node.add(f"[cyan]{cmd_name}[/cyan]  [dim]in {sc.container}: {sc.run}[/dim]")
+    console.print(root)
+
+
+@suppress_known_exceptions
+def stats_command(
+    ctx: typer.Context,
+    follow: Annotated[bool, typer.Option("--follow", "-f", help="Stream stats live.")] = False,
+) -> None:
+    """Show docker resource usage for workspace services (wrapper over ``docker stats``)."""
+    space_path = _resolve_space_path(ctx)
+    resolved = load_space(space_path, strict_vars=_strict_vars(ctx))
+    plan = make_plan(resolved)
+    env = build_env(plan)
+    args = ["docker", "stats"]
+    if not follow:
+        args.append("--no-stream")
+    run_command(args, cwd=plan.project_dir, env=env)
+
+
+__all__ = ("graph_command", "stats_command")