graphpop-cli 0.1.0__py3-none-any.whl

graphpop_cli/commands/run_all.py

@@ -0,0 +1,276 @@
+"""graphpop run-all — orchestrate full-genome analysis across populations and chromosomes."""
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+
+import click
+
+from ..cli import pass_ctx
+from ..config import build_cypher
+
+
+# Default procedures for each phase
+PHASE1_PROCEDURES = [
+    "diversity", "sfs", "pop_summary", "roh", "ihs", "nsl", "garud_h",
+]
+PHASE2_PROCEDURES = ["xpehh", "divergence"]
+
+YIELD_COLS = {
+    "diversity": ["pi", "theta_w", "tajima_d", "fay_wu_h", "fay_wu_h_norm",
+                   "het_exp", "het_obs", "fis", "n_variants", "n_segregating"],
+    "sfs": ["sfs", "n_variants", "max_ac"],
+    "pop_summary": ["pi", "theta_w", "tajima_d", "n_variants", "n_segregating"],
+    "roh": ["sampleId", "n_roh", "total_length", "froh", "mean_length", "max_length"],
+    "ihs": ["variantId", "pos", "af", "ihs_unstd", "ihs"],
+    "nsl": ["variantId", "pos", "af", "nsl_unstd", "nsl"],
+    "garud_h": ["chr", "start", "end", "population", "h1", "h12", "h2_h1",
+                 "hap_diversity", "n_haplotypes", "n_variants"],
+    "xpehh": ["variantId", "pos", "af_pop1", "af_pop2", "xpehh_unstd", "xpehh"],
+    "divergence": ["fst_hudson", "fst_wc", "dxy", "da", "pbs", "n_variants"],
+}
+
+
+def get_chromosome_lengths(ctx) -> dict[str, int]:
+    """Query chromosome lengths from the graph."""
+    cypher = "MATCH (c:Chromosome) RETURN c.chromosomeId AS chr, c.length AS length ORDER BY c.chromosomeId"
+    records = ctx.run(cypher)
+    return {r["chr"]: r["length"] for r in records}
+
+
+def get_populations(ctx) -> list[str]:
+    """Query population IDs from the graph."""
+    cypher = "MATCH (p:Population) WHERE p.n_samples > 1 RETURN p.populationId AS pop ORDER BY p.n_samples DESC"
+    records = ctx.run(cypher)
+    return [r["pop"] for r in records]
+
+
+def get_xpehh_pairs(populations: list[str], max_pairs: int = 20) -> list[tuple[str, str]]:
+    """Generate representative XP-EHH population pairs."""
+    pairs = []
+    for i, p1 in enumerate(populations):
+        for p2 in populations[i + 1:]:
+            pairs.append((p1, p2))
+            if len(pairs) >= max_pairs:
+                return pairs
+    return pairs
+
+
+@click.command("run-all")
+@click.option("--phase", type=click.Choice(["1", "2", "all"]), default="all",
+              help="Phase 1 (per-pop), Phase 2 (pairwise), or all")
+@click.option("--output-dir", "-d", type=click.Path(), default="graphpop_results",
+              help="Output directory for result files")
+@click.option("--resume/--no-resume", default=True,
+              help="Skip already-completed tasks (default: resume)")
+@click.option("--json-output", type=click.Path(),
+              help="Accumulated JSON results file (default: <output-dir>/results.json)")
+@click.option("--persist/--no-persist", default=True,
+              help="Write results to graph nodes (default: yes)")
+@click.option("--populations", "pop_list",
+              help="Comma-separated population list (default: auto-detect)")
+@click.option("--chromosomes", "chr_list",
+              help="Comma-separated chromosome list (default: auto-detect)")
+@click.option("--xpehh-pairs", type=int, default=20,
+              help="Max number of XP-EHH population pairs")
+@click.option("--workers", type=int, default=1,
+              help="Parallel workers (experimental)")
+@pass_ctx
+def run_all(ctx, phase, output_dir, resume, json_output, persist,
+            pop_list, chr_list, xpehh_pairs, workers):
+    """Run full-genome analysis across all populations and chromosomes.
+
+    Phase 1: Per-population statistics (diversity, SFS, iHS, nSL, ROH, Garud's H)
+    for each population × chromosome combination.
+
+    Phase 2: Pairwise statistics (XP-EHH, divergence) for representative
+    population pairs × chromosomes.
+
+    Results are saved as TSV files in the output directory and optionally
+    persisted to graph nodes.
+    """
+    out_dir = Path(output_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    json_path = Path(json_output) if json_output else out_dir / "results.json"
+
+    # Load or initialize results
+    results = {}
+    if resume and json_path.exists():
+        with open(json_path) as f:
+            results = json.load(f)
+        click.echo(f"Resuming from {json_path} ({len(results)} entries)")
+
+    # Auto-detect populations and chromosomes
+    click.echo("Querying graph for populations and chromosomes...")
+    chr_lens = get_chromosome_lengths(ctx)
+    chromosomes = sorted(chr_lens.keys()) if not chr_list else chr_list.split(",")
+    populations = get_populations(ctx) if not pop_list else pop_list.split(",")
+
+    click.echo(f"Populations: {len(populations)} ({', '.join(populations[:5])}...)")
+    click.echo(f"Chromosomes: {len(chromosomes)} ({', '.join(chromosomes[:3])}...)")
+
+    # Phase 1: Per-population
+    if phase in ("1", "all"):
+        click.echo(f"\n=== Phase 1: Per-population ({len(populations)} pops × {len(chromosomes)} chrs) ===")
+        total = len(populations) * len(chromosomes) * len(PHASE1_PROCEDURES)
+        done = 0
+        t0 = time.time()
+
+        for pop in populations:
+            for chrom in chromosomes:
+                for proc in PHASE1_PROCEDURES:
+                    key = f"{pop}_{chrom}_{proc}"
+                    if resume and key in results:
+                        done += 1
+                        continue
+
+                    try:
+                        if proc in ("diversity", "sfs", "pop_summary"):
+                            length = chr_lens.get(chrom, 300_000_000)
+                            cypher = build_cypher(
+                                f"graphpop.{proc}",
+                                [f"'{chrom}'", "1", str(length), f"'{pop}'"],
+                                yield_cols=YIELD_COLS.get(proc),
+                            )
+                        elif proc in ("ihs", "nsl"):
+                            cypher = build_cypher(
+                                f"graphpop.{proc}",
+                                [f"'{chrom}'", f"'{pop}'"],
+                                options={"min_af": 0.05},
+                                yield_cols=["variantId", "pos", "af",
+                                            f"{proc}_unstd", proc],
+                            )
+                        elif proc == "roh":
+                            cypher = build_cypher(
+                                f"graphpop.{proc}",
+                                [f"'{chrom}'", f"'{pop}'"],
+                                yield_cols=YIELD_COLS["roh"],
+                            )
+                        elif proc == "garud_h":
+                            cypher = build_cypher(
+                                f"graphpop.{proc}",
+                                [f"'{chrom}'", f"'{pop}'", "100000", "50000"],
+                                yield_cols=YIELD_COLS["garud_h"],
+                            )
+                        else:
+                            continue
+
+                        records = ctx.run(cypher)
+                        results[key] = {
+                            "population": pop, "chr": chrom, "procedure": proc,
+                            "n_records": len(records),
+                            "summary": records[0] if len(records) == 1 else f"{len(records)} rows",
+                        }
+
+                        # Write per-procedure TSV
+                        tsv_dir = out_dir / proc
+                        tsv_dir.mkdir(exist_ok=True)
+                        tsv_path = tsv_dir / f"{pop}_{chrom}.tsv"
+                        if records:
+                            _write_tsv(tsv_path, records)
+
+                    except Exception as e:
+                        results[key] = {"error": str(e)}
+                        click.echo(f"  ERROR {key}: {e}", err=True)
+
+                    done += 1
+                    elapsed = time.time() - t0
+                    rate = done / elapsed if elapsed > 0 else 0
+                    eta = (total - done) / rate if rate > 0 else 0
+                    if done % 10 == 0:
+                        click.echo(
+                            f"  [{done}/{total}] {key} "
+                            f"({elapsed:.0f}s elapsed, ~{eta:.0f}s remaining)"
+                        )
+
+                # Save checkpoint after each chromosome
+                _save_json(json_path, results)
+
+    # Phase 2: Pairwise
+    if phase in ("2", "all"):
+        pairs = get_xpehh_pairs(populations, xpehh_pairs)
+        click.echo(f"\n=== Phase 2: Pairwise ({len(pairs)} pairs × {len(chromosomes)} chrs) ===")
+
+        for pop1, pop2 in pairs:
+            for chrom in chromosomes:
+                for proc in PHASE2_PROCEDURES:
+                    key = f"{pop1}_vs_{pop2}_{chrom}_{proc}"
+                    if resume and key in results:
+                        continue
+
+                    try:
+                        if proc == "xpehh":
+                            cypher = build_cypher(
+                                "graphpop.xpehh",
+                                [f"'{chrom}'", f"'{pop1}'", f"'{pop2}'"],
+                                options={"min_af": 0.05},
+                                yield_cols=YIELD_COLS["xpehh"],
+                            )
+                        elif proc == "divergence":
+                            length = chr_lens.get(chrom, 300_000_000)
+                            cypher = build_cypher(
+                                "graphpop.divergence",
+                                [f"'{chrom}'", "1", str(length),
+                                 f"'{pop1}'", f"'{pop2}'"],
+                                yield_cols=YIELD_COLS["divergence"],
+                            )
+                        else:
+                            continue
+
+                        records = ctx.run(cypher)
+                        results[key] = {
+                            "pop1": pop1, "pop2": pop2, "chr": chrom,
+                            "procedure": proc, "n_records": len(records),
+                            "summary": records[0] if len(records) == 1 else f"{len(records)} rows",
+                        }
+
+                        tsv_dir = out_dir / proc
+                        tsv_dir.mkdir(exist_ok=True)
+                        tsv_path = tsv_dir / f"{pop1}_vs_{pop2}_{chrom}.tsv"
+                        if records:
+                            _write_tsv(tsv_path, records)
+
+                    except Exception as e:
+                        results[key] = {"error": str(e)}
+                        click.echo(f"  ERROR {key}: {e}", err=True)
+
+                _save_json(json_path, results)
+
+    # Final save
+    _save_json(json_path, results)
+    n_ok = sum(1 for v in results.values() if "error" not in v)
+    n_err = sum(1 for v in results.values() if "error" in v)
+    click.echo(f"\nDone. {n_ok} succeeded, {n_err} failed.")
+    click.echo(f"Results: {json_path}")
+    click.echo(f"TSV files: {out_dir}/")
+
+
+def _write_tsv(path: Path, records: list[dict]):
+    """Write records to a TSV file."""
+    if not records:
+        return
+    keys = list(records[0].keys())
+    with open(path, "w") as f:
+        f.write("\t".join(keys) + "\n")
+        for rec in records:
+            vals = []
+            for k in keys:
+                v = rec[k]
+                if isinstance(v, float):
+                    vals.append(f"{v:.6g}")
+                elif isinstance(v, list):
+                    vals.append(",".join(str(x) for x in v))
+                elif v is None:
+                    vals.append("NA")
+                else:
+                    vals.append(str(v))
+            f.write("\t".join(vals) + "\n")
+
+
+def _save_json(path: Path, data: dict):
+    """Save results as JSON with atomic write."""
+    tmp = path.with_suffix(".tmp")
+    with open(tmp, "w") as f:
+        json.dump(data, f, indent=2, default=str)
+    tmp.rename(path)

graphpop_cli/commands/server.py

@@ -0,0 +1,98 @@
+"""graphpop start/stop/status — Neo4j server lifecycle management."""
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import click
+import yaml
+
+
+def _get_neo4j_home() -> Path:
+    """Get Neo4j home from config or default."""
+    config_path = Path.home() / ".graphpop" / "config.yaml"
+    if config_path.exists():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        if "neo4j_home" in cfg:
+            return Path(cfg["neo4j_home"])
+    # Fallbacks
+    for candidate in [Path.home() / "neo4j", Path("/var/lib/neo4j")]:
+        if (candidate / "bin" / "neo4j").exists():
+            return candidate
+    return Path.home() / "neo4j"
+
+
+def _run_neo4j_cmd(command: str, neo4j_home: Path | None = None) -> tuple[int, str]:
+    """Run a neo4j command and return (returncode, output)."""
+    home = neo4j_home or _get_neo4j_home()
+    neo4j_bin = home / "bin" / "neo4j"
+    if not neo4j_bin.exists():
+        return 1, f"Neo4j not found at {home}. Run 'graphpop setup' first."
+    result = subprocess.run(
+        [str(neo4j_bin), command],
+        capture_output=True, text=True,
+    )
+    output = (result.stdout + result.stderr).strip()
+    return result.returncode, output
+
+
+@click.command()
+@click.option("--neo4j-home", type=click.Path(), help="Neo4j installation directory")
+def start(neo4j_home):
+    """Start the Neo4j database server."""
+    home = Path(neo4j_home) if neo4j_home else None
+    click.echo("Starting Neo4j...")
+    rc, output = _run_neo4j_cmd("start", home)
+    click.echo(output)
+    if rc == 0:
+        click.echo("\nNeo4j started. Use 'graphpop status' to verify.")
+
+
+@click.command()
+@click.option("--neo4j-home", type=click.Path(), help="Neo4j installation directory")
+def stop(neo4j_home):
+    """Stop the Neo4j database server."""
+    home = Path(neo4j_home) if neo4j_home else None
+    click.echo("Stopping Neo4j...")
+    rc, output = _run_neo4j_cmd("stop", home)
+    click.echo(output)
+
+
+@click.command()
+@click.option("--neo4j-home", type=click.Path(), help="Neo4j installation directory")
+def status(neo4j_home):
+    """Check whether Neo4j is running and show database info."""
+    home = Path(neo4j_home) if neo4j_home else _get_neo4j_home()
+
+    # Check Neo4j process
+    rc, output = _run_neo4j_cmd("status", home)
+    click.echo(output)
+
+    # Show version
+    neo4j_bin = home / "bin" / "neo4j"
+    if neo4j_bin.exists():
+        result = subprocess.run([str(neo4j_bin), "version"],
+                                capture_output=True, text=True)
+        if result.returncode == 0:
+            click.echo(f"Version: {result.stdout.strip()}")
+
+    # Show config
+    config_path = Path.home() / ".graphpop" / "config.yaml"
+    if config_path.exists():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        click.echo(f"\nGraphPop config ({config_path}):")
+        click.echo(f"  URI:      {cfg.get('uri', 'not set')}")
+        click.echo(f"  Database: {cfg.get('database', 'not set')}")
+        click.echo(f"  Neo4j:    {cfg.get('neo4j_home', 'not set')}")
+
+    # Show plugin status
+    plugins_dir = home / "plugins"
+    jar_files = list(plugins_dir.glob("graphpop*.jar")) if plugins_dir.exists() else []
+    if jar_files:
+        click.echo(f"\nGraphPop plugin: {jar_files[0].name}")
+    else:
+        click.echo("\nGraphPop plugin: NOT INSTALLED")
+        click.echo("  Build with: cd graphpop-procedures && mvn package")
+        click.echo("  Deploy with: graphpop setup --deploy-plugin target/graphpop-procedures-*.jar")

graphpop_cli/commands/setup.py

@@ -0,0 +1,299 @@
+"""graphpop setup — download, configure, and initialize Neo4j for GraphPop."""
+from __future__ import annotations
+
+import platform
+import shutil
+import subprocess
+import tarfile
+from pathlib import Path
+
+import click
+import yaml
+
+
+
+DEFAULT_NEO4J_HOME = Path.home() / "neo4j"
+NEO4J_VERSION = "5.26.0"
+NEO4J_DOWNLOAD_URL = (
+    f"https://dist.neo4j.org/neo4j-community-{NEO4J_VERSION}-unix.tar.gz"
+)
+
+# GraphPop procedures plugin — auto-downloaded from GitHub Releases
+GRAPHPOP_PROCEDURES_VERSION = "0.1.0"
+GRAPHPOP_JAR_NAME = f"graphpop-procedures-{GRAPHPOP_PROCEDURES_VERSION}.jar"
+GRAPHPOP_JAR_URL = (
+    f"https://github.com/jfmao/GraphPop/releases/download/"
+    f"v{GRAPHPOP_PROCEDURES_VERSION}/{GRAPHPOP_JAR_NAME}"
+)
+
+
+@click.command()
+@click.option("--neo4j-home", type=click.Path(), default=str(DEFAULT_NEO4J_HOME),
+              help=f"Neo4j installation directory (default: {DEFAULT_NEO4J_HOME})")
+@click.option("--pagecache", default="16g",
+              help="Neo4j page cache size (default: 16g)")
+@click.option("--heap", default="4g",
+              help="Neo4j JVM heap size (default: 4g)")
+@click.option("--password", prompt=True, hide_input=True,
+              confirmation_prompt=True,
+              help="Neo4j password for the 'neo4j' user")
+@click.option("--skip-download", is_flag=True,
+              help="Skip downloading Neo4j (use existing installation)")
+@click.option("--deploy-plugin", type=click.Path(exists=True), default=None,
+              help="Path to a local graphpop-procedures.jar (skips auto-download)")
+@click.option("--skip-plugin", is_flag=True,
+              help="Skip deploying the GraphPop procedures plugin")
+def setup(neo4j_home, pagecache, heap, password, skip_download, deploy_plugin,
+          skip_plugin):
+    """Set up Neo4j for GraphPop.
+
+    Downloads Neo4j Community Edition, automatically downloads and deploys
+    the pre-compiled GraphPop procedures plugin, configures memory settings,
+    sets the initial password, and creates the GraphPop config file.
+
+    No Java or Maven installation is required — the plugin is downloaded as
+    a pre-compiled JAR from GitHub Releases.
+
+    \b
+    Examples:
+      graphpop setup --password mypass
+      graphpop setup --neo4j-home /opt/neo4j --pagecache 20g --heap 8g
+      graphpop setup --deploy-plugin path/to/local/graphpop-procedures.jar
+      graphpop setup --skip-plugin --password mypass
+    """
+    neo4j_path = Path(neo4j_home)
+
+    # Step 0: Check Java runtime
+    _check_java()
+
+    # Step 1: Download Neo4j
+    if not skip_download:
+        if neo4j_path.exists() and (neo4j_path / "bin" / "neo4j").exists():
+            click.echo(f"Neo4j already installed at {neo4j_path}")
+            if not click.confirm("Re-install?"):
+                skip_download = True
+
+    if not skip_download:
+        _download_neo4j(neo4j_path)
+
+    # Verify installation
+    neo4j_bin = neo4j_path / "bin" / "neo4j"
+    if not neo4j_bin.exists():
+        click.echo(f"Error: Neo4j not found at {neo4j_path}", err=True)
+        click.echo("Use --neo4j-home to specify the installation directory.", err=True)
+        raise SystemExit(1)
+
+    # Step 2: Configure Neo4j
+    click.echo("\nConfiguring Neo4j...")
+    _configure_neo4j(neo4j_path, pagecache, heap)
+
+    # Step 3: Set initial password
+    click.echo("Setting Neo4j password...")
+    _set_password(neo4j_path, password)
+
+    # Step 4: Deploy GraphPop plugin
+    # Priority: user-provided JAR > conda-bundled JAR > GitHub download
+    plugin_dest = neo4j_path / "plugins" / "graphpop-procedures.jar"
+    if deploy_plugin:
+        # Use user-provided local JAR
+        click.echo(f"Deploying GraphPop plugin from {deploy_plugin}...")
+        shutil.copy2(deploy_plugin, plugin_dest)
+        click.echo(f"  Deployed to {plugin_dest}")
+    elif not skip_plugin:
+        # Check for conda-bundled JAR first
+        conda_jar = _find_conda_jar()
+        if conda_jar:
+            click.echo(f"Deploying conda-bundled GraphPop plugin...")
+            shutil.copy2(conda_jar, plugin_dest)
+            click.echo(f"  Deployed to {plugin_dest}")
+        else:
+            # Auto-download pre-compiled JAR from GitHub Releases
+            click.echo(f"Downloading GraphPop procedures plugin v{GRAPHPOP_PROCEDURES_VERSION}...")
+            _download_plugin(plugin_dest)
+            click.echo(f"  Deployed to {plugin_dest}")
+
+    # Step 5: Create GraphPop config
+    config_dir = Path.home() / ".graphpop"
+    config_dir.mkdir(exist_ok=True)
+    config_path = config_dir / "config.yaml"
+
+    config = {
+        "uri": "bolt://localhost:7687",
+        "user": "neo4j",
+        "password": password,
+        "database": "neo4j",
+        "neo4j_home": str(neo4j_path),
+    }
+    with open(config_path, "w") as f:
+        yaml.dump(config, f, default_flow_style=False)
+    click.echo(f"\nGraphPop config written to {config_path}")
+
+    # Step 6: Summary
+    click.echo(f"""
+Setup complete!
+
+  Neo4j home:    {neo4j_path}
+  Page cache:    {pagecache}
+  Heap:          {heap}
+  Config:        {config_path}
+  Plugin:        {'deployed' if (deploy_plugin or not skip_plugin) else 'not deployed (use --deploy-plugin or remove --skip-plugin)'}
+
+Next steps:
+  graphpop start                         # Start Neo4j
+  graphpop import --vcf data.vcf.gz \\
+    --panel panel.txt --database mydb    # Import data
+  graphpop diversity chr1 1 50000000 POP # Run analysis
+""")
+
+
+def _download_neo4j(dest: Path):
+    """Download and extract Neo4j Community Edition."""
+    import urllib.request
+
+    tarball = Path(f"/tmp/neo4j-community-{NEO4J_VERSION}-unix.tar.gz")
+    if tarball.exists():
+        click.echo(f"Using cached download: {tarball}")
+    else:
+        click.echo(f"Downloading Neo4j {NEO4J_VERSION}...")
+        click.echo(f"  URL: {NEO4J_DOWNLOAD_URL}")
+        urllib.request.urlretrieve(NEO4J_DOWNLOAD_URL, tarball)
+        click.echo(f"  Downloaded to {tarball}")
+
+    click.echo(f"Extracting to {dest}...")
+    if dest.exists():
+        shutil.rmtree(dest)
+
+    with tarfile.open(tarball) as tf:
+        tf.extractall(dest.parent)
+
+    # The tarball extracts to neo4j-community-X.Y.Z/
+    extracted = dest.parent / f"neo4j-community-{NEO4J_VERSION}"
+    if extracted.exists() and extracted != dest:
+        extracted.rename(dest)
+    click.echo(f"  Installed to {dest}")
+
+
+def _configure_neo4j(neo4j_home: Path, pagecache: str, heap: str):
+    """Configure Neo4j memory and settings."""
+    conf_path = neo4j_home / "conf" / "neo4j.conf"
+
+    # Read existing config
+    lines = conf_path.read_text().splitlines() if conf_path.exists() else []
+
+    # Settings to apply
+    settings = {
+        "server.memory.pagecache.size": pagecache,
+        "server.memory.heap.initial_size": heap,
+        "server.memory.heap.max_size": heap,
+        "server.directories.import": "import",
+        "db.tx_log.rotation.retention_policy": "2 days 2G",
+        "dbms.security.procedures.unrestricted": "graphpop.*",
+    }
+
+    # Update or append settings
+    updated_keys = set()
+    new_lines = []
+    for line in lines:
+        key = line.split("=")[0].strip() if "=" in line and not line.startswith("#") else None
+        if key and key in settings:
+            new_lines.append(f"{key}={settings[key]}")
+            updated_keys.add(key)
+        else:
+            new_lines.append(line)
+
+    # Append settings not yet in config
+    for key, value in settings.items():
+        if key not in updated_keys:
+            new_lines.append(f"{key}={value}")
+
+    conf_path.write_text("\n".join(new_lines) + "\n")
+    for k, v in settings.items():
+        click.echo(f"  {k}={v}")
+
+
+def _check_java():
+    """Verify that Java 21+ is available for Neo4j runtime."""
+    try:
+        result = subprocess.run(
+            ["java", "-version"], capture_output=True, text=True,
+        )
+        output = result.stderr + result.stdout  # java -version prints to stderr
+        click.echo(f"  Java found: {output.splitlines()[0].strip()}")
+        # Check version >= 21
+        import re
+        m = re.search(r'"(\d+)', output)
+        if m and int(m.group(1)) < 21:
+            click.echo(
+                "  Warning: Java 21+ is required by Neo4j. "
+                "Found version {m.group(1)}.\n"
+                "  Install via: conda install -c conda-forge openjdk=21\n"
+                "  Or: sudo apt install openjdk-21-jre-headless",
+                err=True,
+            )
+    except FileNotFoundError:
+        click.echo(
+            "Error: Java not found. Neo4j requires Java 21+ to run.\n"
+            "Install via:\n"
+            "  conda install -c conda-forge openjdk=21\n"
+            "  Or: sudo apt install openjdk-21-jre-headless",
+            err=True,
+        )
+        raise SystemExit(1)
+
+
+def _find_conda_jar() -> Path | None:
+    """Look for a GraphPop JAR bundled by conda in the environment prefix."""
+    import sys
+    conda_prefix = Path(sys.prefix)
+    candidates = [
+        conda_prefix / "share" / "graphpop" / "plugins" / "graphpop-procedures.jar",
+        conda_prefix / "lib" / "graphpop" / "graphpop-procedures.jar",
+    ]
+    for p in candidates:
+        if p.exists():
+            return p
+    return None
+
+
+def _download_plugin(dest: Path):
+    """Download the pre-compiled GraphPop procedures JAR from GitHub Releases."""
+    import urllib.request
+
+    cache = Path(f"/tmp/{GRAPHPOP_JAR_NAME}")
+    if cache.exists():
+        click.echo(f"  Using cached plugin: {cache}")
+    else:
+        click.echo(f"  URL: {GRAPHPOP_JAR_URL}")
+        try:
+            urllib.request.urlretrieve(GRAPHPOP_JAR_URL, cache)
+        except Exception as e:
+            click.echo(f"  Error downloading plugin: {e}", err=True)
+            click.echo(
+                "  You can build locally instead:\n"
+                "    cd graphpop-procedures && ./mvnw package -DskipTests\n"
+                "    graphpop setup --deploy-plugin target/graphpop-procedures-0.1.0-SNAPSHOT.jar",
+                err=True,
+            )
+            raise SystemExit(1)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(cache, dest)
+
+
+def _set_password(neo4j_home: Path, password: str):
+    """Set the initial Neo4j password."""
+    admin_bin = neo4j_home / "bin" / "neo4j-admin"
+    try:
+        result = subprocess.run(
+            [str(admin_bin), "dbms", "set-initial-password", password],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0:
+            click.echo("  Password set successfully")
+        else:
+            # May already be set
+            if "already" in result.stderr.lower() or "already" in result.stdout.lower():
+                click.echo("  Password already set (use Neo4j browser to change)")
+            else:
+                click.echo(f"  Warning: {result.stderr.strip()}")
+    except FileNotFoundError:
+        click.echo("  Warning: neo4j-admin not found, skipping password setup")