civex 1.0.0__py3-none-any.whl

civex/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("civex")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"

civex/cli/_docker.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import re
+import socket
+import subprocess
+import time
+
+from civex.console import console
+
+
+def docker_available() -> bool:
+    """Return True if Docker is installed and the current user can reach the socket."""
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=15,
+        )
+        return result.returncode == 0
+    except FileNotFoundError:
+        return False
+    except subprocess.TimeoutExpired:
+        return False
+
+
+def docker_error_hint() -> str:
+    """Return a human-readable reason why Docker isn't usable."""
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        if result.returncode == 0:
+            return ""
+        combined = (result.stdout + result.stderr).lower()
+        if "permission denied" in combined and "docker.sock" in combined:
+            import getpass
+            user = getpass.getuser()
+            return (
+                f"Permission denied on the Docker socket.\n"
+                f"  Fix:  sudo usermod -aG docker {user}\n"
+                f"  Then: newgrp docker    (or log out and back in)"
+            )
+        if "cannot connect" in combined or "is the docker daemon running" in combined:
+            return "Docker daemon is not running. Start Docker Desktop or run: sudo systemctl start docker"
+        return result.stderr.strip() or "docker info returned a non-zero exit code"
+    except FileNotFoundError:
+        return "Docker is not installed. See https://www.docker.com/products/docker-desktop"
+    except subprocess.TimeoutExpired:
+        return "docker info timed out — Docker may be starting up, try again in a moment"
+
+
+def container_name(project_name: str) -> str:
+    safe = re.sub(r"[^a-zA-Z0-9_-]", "-", project_name).strip("-")
+    return f"civex-{safe or 'project'}"
+
+
+def find_free_port(preferred: int = 5432) -> int:
+    try:
+        s = socket.socket()
+        s.bind(("", preferred))
+        s.close()
+        return preferred
+    except OSError:
+        s = socket.socket()
+        s.bind(("", 0))
+        port = s.getsockname()[1]
+        s.close()
+        return port
+
+
+def start_pg_container(name: str, port: int) -> tuple[bool, str]:
+    """Start or create the civex postgres container. Returns (ok, error_message)."""
+    # Reuse existing container if it already exists
+    inspect = subprocess.run(
+        ["docker", "inspect", "--format", "{{.State.Status}}", name],
+        capture_output=True,
+        text=True,
+    )
+    if inspect.returncode == 0:
+        status = inspect.stdout.strip()
+        if status != "running":
+            subprocess.run(["docker", "start", name], capture_output=True)
+        return True, ""
+
+    result = subprocess.run(
+        [
+            "docker", "run", "-d",
+            "--name", name,
+            "-p", f"{port}:5432",
+            "-e", "POSTGRES_HOST_AUTH_METHOD=trust",
+            "-e", "POSTGRES_DB=civex",
+            "-v", f"{name}-pgdata:/var/lib/postgresql/data",
+            "--restart", "unless-stopped",
+            "postgres:16",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        return False, result.stderr.strip()
+    return True, ""
+
+
+def wait_for_postgres(port: int, timeout: int = 60) -> bool:
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            result = subprocess.run(
+                ["pg_isready", "-h", "localhost", "-p", str(port), "-q"],
+                capture_output=True,
+                timeout=3,
+            )
+            if result.returncode == 0:
+                return True
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            # pg_isready not available — fall back to raw socket probe
+            try:
+                s = socket.create_connection(("localhost", port), timeout=1)
+                s.close()
+                return True
+            except OSError:
+                pass
+        time.sleep(1)
+    return False
+
+
+def setup_docker_postgres(project_name: str) -> str | None:
+    """
+    Spin up (or reuse) a Docker postgres container for this project.
+    Returns a SQLAlchemy URL on success, None on failure.
+    """
+    name = container_name(project_name)
+    port = find_free_port(5432)
+
+    console.print("\nSetting up PostgreSQL via Docker...")
+    console.print(f"  Starting container [bold]{name}[/bold]...", end="  ")
+
+    ok, err = start_pg_container(name, port)
+    if not ok:
+        console.print("[error]FAILED[/error]")
+        console.print(f"  [dim]{err}[/dim]")
+        return None
+    console.print("[success]OK[/success]")
+
+    console.print("  Waiting for PostgreSQL...", end="         ")
+    if not wait_for_postgres(port):
+        console.print("[error]timed out[/error]")
+        console.print(
+            "  [dim]Container started but postgres didn't respond within 60s.[/dim]"
+        )
+        return None
+    console.print("[success]OK[/success]")
+
+    return f"postgresql+psycopg2://postgres@localhost:{port}/civex"

civex/cli/auth.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+import typer
+
+from civex.console import console
+
+app = typer.Typer(help="Authenticate with a civex-hub server.")
+
+_TOKENS_PATH = Path.home() / ".civex" / "tokens.toml"
+
+
+def _read_tokens() -> dict:
+    if not _TOKENS_PATH.exists():
+        return {}
+    with open(_TOKENS_PATH, "rb") as f:
+        return tomllib.load(f)
+
+
+def _write_tokens(data: dict) -> None:
+    _TOKENS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    lines = []
+    for url, entry in data.items():
+        lines.append(f'["{url}"]\n')
+        for k, v in entry.items():
+            lines.append(f'{k} = "{v}"\n')
+        lines.append("\n")
+    _TOKENS_PATH.write_text("".join(lines))
+
+
+@app.command("login")
+def login(
+    hub_url: str = typer.Argument(..., help="civex-hub base URL (e.g. https://civexhub.example.com)"),
+    username: str = typer.Option(None, "--username", "-u", help="Your username"),
+    token_name: str = typer.Option("default", "--token-name", help="Label for this token"),
+) -> None:
+    """Log in to a civex-hub server and store an API token."""
+    import urllib.request
+    import urllib.error
+    import json
+
+    hub_url = hub_url.rstrip("/")
+
+    if not username:
+        username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True)
+
+    payload = json.dumps({"username": username, "password": password, "name": token_name}).encode()
+    req = urllib.request.Request(
+        f"{hub_url}/auth/tokens",
+        data=payload,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req) as resp:
+            result = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode(errors="replace")
+        console.print(f"[red]Login failed ({e.code}):[/red] {body}")
+        raise typer.Exit(1)
+    except Exception as e:
+        console.print(f"[red]Connection error:[/red] {e}")
+        raise typer.Exit(1)
+
+    raw_token = result.get("token")
+    if not raw_token:
+        console.print("[red]Unexpected response — no token received.[/red]")
+        raise typer.Exit(1)
+
+    tokens = _read_tokens()
+    tokens[hub_url] = {"token": raw_token, "username": username}
+    _write_tokens(tokens)
+
+    console.print(f"[green]Logged in to {hub_url} as {username}.[/green]")
+    console.print(f"  Token saved to {_TOKENS_PATH}")
+
+
+@app.command("logout")
+def logout(
+    hub_url: str = typer.Argument(None, help="Hub URL to log out from (omit to log out of all)"),
+) -> None:
+    """Remove stored credentials for a civex-hub server."""
+    tokens = _read_tokens()
+    if not tokens:
+        console.print("[dim]Not logged in to any hub.[/dim]")
+        return
+
+    if hub_url:
+        hub_url = hub_url.rstrip("/")
+        if hub_url not in tokens:
+            console.print(f"[dim]Not logged in to {hub_url}.[/dim]")
+            return
+        del tokens[hub_url]
+        _write_tokens(tokens)
+        console.print(f"[success]Logged out of {hub_url}.[/success]")
+    else:
+        _write_tokens({})
+        console.print("[success]Logged out of all hubs.[/success]")
+
+
+@app.command("status")
+def status() -> None:
+    """Show which civex-hub servers you are logged in to."""
+    tokens = _read_tokens()
+    if not tokens:
+        console.print("[dim]Not logged in to any hub.[/dim]")
+        return
+    for url, entry in tokens.items():
+        console.print(f"  {url}  ([dim]{entry.get('username', '?')}[/dim])")

civex/cli/clone.py

@@ -0,0 +1,93 @@
+"""
+civex clone <url> [local-dir] [--remote-civex <path>]
+
+Clones a bare repository into a new local working directory.
+Database rows are transferred via DTOs (SyncBundle). Objects are NOT downloaded
+immediately — they are fetched on demand when accessed (lazy).
+
+Use --remote-civex when civex is not on PATH on the remote (e.g. installed in a venv):
+    civex clone ssh://js521/~/civex-test-repo --remote-civex ~/venv/bin/civex
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session
+
+from civex.console import console
+from civex.db.models import Base
+from civex.sync.importer import apply_bundle
+from civex.sync.transport import SyncError, get_transport
+
+
+def clone(
+    url: str = typer.Argument(..., help="Remote URL (ssh://user@host/path or file:///path)"),
+    local_dir: Path = typer.Argument(None, help="Destination directory (default: derived from URL)"),
+    remote_civex: str = typer.Option(
+        "civex",
+        "--remote-civex",
+        help="Path to the civex executable on the remote (use when civex is in a venv, e.g. ~/venv/bin/civex)",
+    ),
+) -> None:
+    """Clone a remote bare repository into a new local project."""
+    try:
+        transport, _remote_path = get_transport(url, remote_civex=remote_civex)
+    except SyncError as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+    # Derive local directory name from the URL if not specified.
+    if local_dir is None:
+        last = url.rstrip("/").rsplit("/", 1)[-1]
+        if last.endswith(".civex"):
+            last = last[: -len(".civex")]
+        local_dir = Path(last or "civex-repo")
+
+    local_dir = local_dir.resolve()
+    civex_dir = local_dir / ".civex"
+
+    if civex_dir.exists():
+        console.print(f"[error]Directory {local_dir} is already a civex project.[/error]")
+        raise typer.Exit(1)
+
+    console.print(f"Cloning from [bold]{url}[/bold] into [bold]{local_dir}[/bold] ...")
+
+    # Fetch the full bundle before creating any local state.
+    try:
+        bundle = transport.transfer_pack(since_seq=0)
+    except SyncError as e:
+        console.print(f"[error]Clone failed: {e}[/error]")
+        raise typer.Exit(1)
+
+    # Create local project structure.
+    civex_dir.mkdir(parents=True)
+    db_path = civex_dir / "civex.db"
+    db_url = f"sqlite:///{db_path.as_posix()}"
+
+    (civex_dir / "objects").mkdir()
+    (civex_dir / "workflows").mkdir()
+    (civex_dir / "plugins").mkdir()
+
+    engine = create_engine(db_url)
+    Base.metadata.create_all(engine)
+
+    with Session(engine) as session:
+        apply_bundle(session, bundle)
+        session.commit()
+    engine.dispose()
+
+    remote_lines = f'[db]\nurl = "{db_url}"\n\n[remote]\nurl = "{url}"\n'
+    if remote_civex != "civex":
+        remote_lines += f'remote_civex = "{remote_civex}"\n'
+    remote_lines += f'last_pulled_seq = {bundle.to_seq}\n'
+    remote_lines += 'last_pushed_seq = 0\n'
+    (civex_dir / "config.toml").write_text(remote_lines)
+
+    console.print("[success]Cloned successfully.[/success]")
+    console.print(f"  Schemas    {len(bundle.schemas)}")
+    console.print(f"  Datasets   {len(bundle.datasets)}")
+    console.print(f"  Records    {len(bundle.records)}")
+    console.print(f"  Objects    {len(bundle.object_refs)} available remotely (fetched on demand)")
+    console.print(f"  Local dir  {local_dir}")

civex/cli/dataset.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import uuid
+from collections import Counter
+from typing import Optional
+
+import typer
+from rich.table import Table
+from rich.tree import Tree
+
+from civex.cli.utils import get_ctx as _ctx
+from civex.console import console
+from civex.domain.dtos import SchemaDTO
+from civex.domain.exceptions import AlreadyExistsError, NotFoundError
+
+app = typer.Typer(help="Manage datasets (named containers for studies or investigations)")
+
+
+@app.command("create")
+def dataset_create(
+    name: str = typer.Argument(...),
+    description: Optional[str] = typer.Option(None, "--description", "-d"),
+) -> None:
+    """Create a new dataset."""
+    ctx = _ctx()
+    try:
+        dataset = ctx.dataset_svc.create(name, description=description)
+        ctx.commit()
+        console.print(f"[success]Created dataset '{dataset.name}'.[/success]")
+    except AlreadyExistsError as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+
+@app.command("list")
+def dataset_list() -> None:
+    """List all datasets."""
+    ctx = _ctx()
+    datasets = ctx.dataset_svc.list_all()
+    if not datasets:
+        console.print("[info]No datasets yet. Use `civex dataset create` to add one.[/info]")
+        return
+
+    table = Table("Name", "Records", "Description")
+    for d in datasets:
+        table.add_row(d.name, str(d.record_count), d.description or "")
+    console.print(table)
+
+
+@app.command("show")
+def dataset_show(name: str = typer.Argument(...)) -> None:
+    """Show a dataset summary with record counts per schema."""
+    ctx = _ctx()
+    try:
+        d = ctx.dataset_svc.get(name)
+    except NotFoundError as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+    console.print(f"[bold]{d.name}[/bold]")
+    console.print(f"  Records  {d.record_count}")
+    if d.description:
+        console.print(f"  {d.description}")
+
+    if d.record_count > 0:
+        records = ctx.record_svc.find(name, schema_name=None, filters=[], limit=100_000)
+        counts = Counter(r.schema_name for r in records)
+        table = Table("Schema", "Records")
+        for schema_name, count in sorted(counts.items()):
+            table.add_row(schema_name, str(count))
+        console.print(table)
+
+
+@app.command("update")
+def dataset_update(
+    name: str = typer.Argument(...),
+    rename: Optional[str] = typer.Option(None, "--rename", help="New name for the dataset"),
+    description: Optional[str] = typer.Option(None, "--description", "-d"),
+) -> None:
+    """Update a dataset's name or description."""
+    if rename is None and description is None:
+        console.print("[error]Provide at least one of --rename or --description.[/error]")
+        raise typer.Exit(1)
+    ctx = _ctx()
+    try:
+        dataset = ctx.dataset_svc.update(name, new_name=rename, description=description)
+        ctx.commit()
+        if rename and rename != name:
+            console.print(
+                f"[warning]Workflow configs that reference '{name}' by name will need updating.[/warning]"
+            )
+        console.print(f"[success]Updated dataset '{dataset.name}'.[/success]")
+    except (NotFoundError, AlreadyExistsError) as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+
+@app.command("delete")
+def dataset_delete(
+    name: str = typer.Argument(...),
+    yes: bool = typer.Option(False, "--yes", "-y"),
+) -> None:
+    """Delete a dataset and all its records."""
+    if not yes:
+        typer.confirm(f"Delete dataset '{name}' and all its records?", abort=True)
+    ctx = _ctx()
+    try:
+        ctx.dataset_svc.delete(name)
+        ctx.commit()
+        console.print(f"[success]Deleted '{name}'.[/success]")
+    except NotFoundError as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+
+@app.command("graph")
+def dataset_graph(name: str = typer.Argument(...)) -> None:
+    """Show the schema hierarchy for schemas present in a dataset."""
+    ctx = _ctx()
+    try:
+        ctx.dataset_svc.get(name)
+    except NotFoundError as e:
+        console.print(f"[error]{e}[/error]")
+        raise typer.Exit(1)
+
+    records = ctx.record_svc.find(name, schema_name=None, filters=[], limit=100_000)
+    if not records:
+        console.print("[info]Dataset has no records yet.[/info]")
+        return
+
+    schema_counts: Counter[uuid.UUID] = Counter(r.schema_id for r in records)
+    schema_ids_present = set(schema_counts)
+
+    all_schemas = ctx.schema_svc.list_all()
+    by_id: dict[uuid.UUID, SchemaDTO] = {s.id: s for s in all_schemas}
+
+    # Find root ancestors of all present schemas.
+    def _root(schema_id: uuid.UUID) -> uuid.UUID:
+        s = by_id.get(schema_id)
+        while s and s.parent_id and s.parent_id in by_id:
+            s = by_id[s.parent_id]
+        return s.id if s else schema_id
+
+    roots = {_root(sid) for sid in schema_ids_present}
+
+    children: dict[uuid.UUID, list[SchemaDTO]] = {}
+    for s in all_schemas:
+        if s.parent_id:
+            children.setdefault(s.parent_id, []).append(s)
+
+    def _label(schema: SchemaDTO) -> str:
+        count = schema_counts.get(schema.id, 0)
+        if schema.id in schema_ids_present:
+            return f"[bold]{schema.name}[/bold] [dim]({count} record{'s' if count != 1 else ''})[/dim]"
+        return f"[dim]{schema.name}[/dim]"
+
+    def _build(schema: SchemaDTO, branch: Tree) -> None:
+        for child in sorted(children.get(schema.id, []), key=lambda s: s.name):
+            _build(child, branch.add(_label(child)))
+
+    for root_id in sorted(roots, key=lambda i: by_id[i].name):
+        root = by_id[root_id]
+        tree = Tree(_label(root))
+        _build(root, tree)
+        console.print(tree)