graphpop-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphpop-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Graph database-native population genomics CLI with O(V*K) complexity
 Author: Jianfeng Mao
 License: MIT

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "graphpop-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Graph database-native population genomics CLI with O(V*K) complexity"
 readme = "README.md"
 license = {text = "MIT"}

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/__init__.py

@@ -1,2 +1,2 @@
 """GraphPop CLI — command-line interface for graph-native population genomics."""
-__version__ = "0.1.0"
+__version__ = "0.1.1"

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/cli.py

@@ -95,7 +95,7 @@ from .commands import (  # noqa: E402
     genome_scan, pop_summary,
     ld, ihs, xpehh, nsl, roh, garud_h,
     query, run_all, aggregate, export_windows,
-    setup, server, db, import_data, dump,
+    setup, server, doctor, db, import_data, dump,
     config_cmd, validate, filter_results, plot,
     lookup, converge, inventory, rank_genes,
     extract, export_bed, batch, compare,
@@ -128,6 +128,7 @@ main.add_command(setup.setup)
 main.add_command(server.start)
 main.add_command(server.stop)
 main.add_command(server.status)
+main.add_command(doctor.doctor)
 
 # Database management
 main.add_command(db.db)

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/compare.py

@@ -1,26 +1,11 @@
 """graphpop compare — compare statistics between two populations."""
 from __future__ import annotations
 
-import re
-
 import click
 
 from ..cli import pass_ctx
 from ..formatters import format_output
-
-# Allowed stat names — used to whitelist dynamic property access
-_VALID_STATS = {"pi", "theta_w", "tajima_d", "fst", "ihs"}
-_IDENT_RE = re.compile(r'^[A-Za-z0-9_-]+$')
-
-
-def _validate_identifier(value: str, label: str) -> str:
-    """Validate that a value is safe for use as a Cypher property name."""
-    if not _IDENT_RE.match(value):
-        raise click.BadParameter(
-            f"Invalid {label}: {value!r}. Only alphanumeric, hyphen, "
-            "and underscore characters are allowed."
-        )
-    return value
+from ..validators import validate_identifier
 
 
 @click.command("compare")
@@ -54,8 +39,8 @@ def compare(ctx, pop1, pop2, chr, stat, window_size, output_path, fmt, limit):
       graphpop compare EUR EAS chr22 --stat ihs -o ihs_diff.tsv
     """
     # Validate identifiers used in dynamic property names
-    pop1 = _validate_identifier(pop1, "population")
-    pop2 = _validate_identifier(pop2, "population")
+    pop1 = validate_identifier(pop1, "population")
+    pop2 = validate_identifier(pop2, "population")
 
     if stat == "ihs":
         records = _compare_variant_stat(ctx, pop1, pop2, chr, stat, limit)

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/converge.py

@@ -5,6 +5,7 @@ import click
 
 from ..cli import pass_ctx
 from ..formatters import format_output
+from ..validators import validate_identifier
 
 
 # Statistics stored on Variant nodes vs GenomicWindow nodes
@@ -45,6 +46,11 @@ def converge(ctx, stats, thresholds, chromosome, population, pop2,
       graphpop converge --stats h12,fst --thresholds 0.3,0.5 --pop GJ-tmp --window 100000
       graphpop converge --stats ihs,xpehh,h12,fst --thresholds 2.0,2.0,0.3,0.5 --pop EUR --pop2 AFR
     """
+    # Validate identifiers used in dynamic property names
+    validate_identifier(population, "population")
+    if pop2:
+        validate_identifier(pop2, "population")
+
     stat_list = [s.strip() for s in stats.split(",")]
     thresh_list = [float(t.strip()) for t in thresholds.split(",")]
 

graphpop_cli-0.1.1/src/graphpop_cli/commands/doctor.py

@@ -0,0 +1,172 @@
+"""graphpop doctor — installation health check."""
+from __future__ import annotations
+
+import re
+import socket
+import subprocess
+from pathlib import Path
+
+import click
+import yaml
+
+from .setup import DEFAULT_BOLT_PORT, DEFAULT_HTTP_PORT
+
+
+def _check(label: str, ok: bool, detail: str = "") -> bool:
+    """Print a check result and return whether it passed."""
+    mark = click.style("OK", fg="green") if ok else click.style("FAIL", fg="red")
+    msg = f"  [{mark}] {label}"
+    if detail:
+        msg += f" — {detail}"
+    click.echo(msg)
+    return ok
+
+
+@click.command()
+def doctor():
+    """Run a full health check on the GraphPop installation.
+
+    Verifies Java, Neo4j home directory, running process, port reachability,
+    plugin deployment, config file, and password connectivity.
+    """
+    click.echo("GraphPop Doctor\n")
+    all_ok = True
+
+    # 1. Java
+    click.echo("Checking Java...")
+    java_ok, java_detail = _check_java_health()
+    all_ok &= _check("Java 21+", java_ok, java_detail)
+
+    # 2. Config file
+    click.echo("\nChecking configuration...")
+    config_path = Path.home() / ".graphpop" / "config.yaml"
+    cfg = {}
+    if config_path.exists():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        all_ok &= _check("Config file", True, str(config_path))
+    else:
+        all_ok &= _check("Config file", False,
+                          f"{config_path} not found — run 'graphpop setup'")
+
+    # 3. Neo4j home
+    click.echo("\nChecking Neo4j installation...")
+    neo4j_home = Path(cfg.get("neo4j_home", Path.home() / "neo4j"))
+    neo4j_bin = neo4j_home / "bin" / "neo4j"
+    if neo4j_bin.exists():
+        all_ok &= _check("Neo4j home", True, str(neo4j_home))
+    else:
+        all_ok &= _check("Neo4j home", False,
+                          f"neo4j binary not found at {neo4j_home}")
+
+    # 4. Neo4j version
+    if neo4j_bin.exists():
+        result = subprocess.run(
+            [str(neo4j_bin), "version"], capture_output=True, text=True,
+        )
+        version_str = result.stdout.strip() if result.returncode == 0 else "unknown"
+        all_ok &= _check("Neo4j version", result.returncode == 0, version_str)
+
+    # 5. Plugin deployment
+    click.echo("\nChecking plugin...")
+    plugins_dir = neo4j_home / "plugins"
+    jar_files = list(plugins_dir.glob("graphpop*.jar")) if plugins_dir.exists() else []
+    if jar_files:
+        all_ok &= _check("GraphPop plugin", True, jar_files[0].name)
+    else:
+        all_ok &= _check("GraphPop plugin", False,
+                          "not found in plugins/ — run 'graphpop setup'")
+
+    # 6. Neo4j process
+    click.echo("\nChecking Neo4j process...")
+    if neo4j_bin.exists():
+        result = subprocess.run(
+            [str(neo4j_bin), "status"], capture_output=True, text=True,
+        )
+        output = (result.stdout + result.stderr).strip()
+        running = result.returncode == 0 and "running" in output.lower()
+        all_ok &= _check("Neo4j running", running,
+                          output.splitlines()[0] if output else "no output")
+    else:
+        all_ok &= _check("Neo4j running", False, "neo4j binary not found")
+
+    # 7. Port reachability
+    click.echo("\nChecking ports...")
+    uri = cfg.get("uri", f"bolt://localhost:{DEFAULT_BOLT_PORT}")
+    # Parse port from URI
+    port_match = re.search(r":(\d+)$", uri)
+    bolt_port = int(port_match.group(1)) if port_match else DEFAULT_BOLT_PORT
+
+    bolt_ok = _is_port_open("127.0.0.1", bolt_port)
+    all_ok &= _check(f"Bolt port {bolt_port}", bolt_ok,
+                      "reachable" if bolt_ok else "not reachable")
+
+    # Check HTTP port from config
+    http_port = cfg.get("http_port", DEFAULT_HTTP_PORT)
+    http_ok = _is_port_open("127.0.0.1", http_port)
+    all_ok &= _check(f"HTTP port {http_port}", http_ok,
+                      "reachable" if http_ok else "not reachable")
+
+    # 8. Bolt connectivity (if neo4j driver available)
+    click.echo("\nChecking database connectivity...")
+    password = cfg.get("password")
+    if password and bolt_ok:
+        conn_ok, conn_detail = _check_bolt_connectivity(uri, password)
+        all_ok &= _check("Bolt connection", conn_ok, conn_detail)
+    elif not bolt_ok:
+        all_ok &= _check("Bolt connection", False,
+                          "skipped — port not reachable")
+    else:
+        all_ok &= _check("Bolt connection", False,
+                          "skipped — no password in config")
+
+    # Summary
+    click.echo("")
+    if all_ok:
+        click.echo(click.style("All checks passed.", fg="green"))
+    else:
+        click.echo(click.style(
+            "Some checks failed. Review the output above.", fg="yellow"))
+    raise SystemExit(0 if all_ok else 1)
+
+
+def _check_java_health() -> tuple[bool, str]:
+    """Return (ok, detail) for Java version check."""
+    try:
+        result = subprocess.run(
+            ["java", "-version"], capture_output=True, text=True,
+        )
+        output = result.stderr + result.stdout
+        first_line = output.splitlines()[0].strip() if output else "unknown"
+        m = re.search(r'"(\d+)', output)
+        if m and int(m.group(1)) >= 21:
+            return True, first_line
+        elif m:
+            return False, f"{first_line} (need 21+, found {m.group(1)})"
+        return False, f"{first_line} (could not parse version)"
+    except FileNotFoundError:
+        return False, "java not found — install via: conda install -c conda-forge openjdk=21"
+
+
+def _is_port_open(host: str, port: int, timeout: float = 2.0) -> bool:
+    """Check if a TCP port is accepting connections."""
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except (OSError, ConnectionRefusedError):
+        return False
+
+
+def _check_bolt_connectivity(uri: str, password: str) -> tuple[bool, str]:
+    """Try a Bolt connection and return (ok, detail)."""
+    try:
+        from neo4j import GraphDatabase
+        driver = GraphDatabase.driver(uri, auth=("neo4j", password))
+        driver.verify_connectivity()
+        info = driver.get_server_info()
+        driver.close()
+        return True, f"connected to {info.agent}"
+    except ImportError:
+        return False, "neo4j-driver not installed — pip install neo4j"
+    except Exception as e:
+        return False, str(e)

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/export_bed.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 import click
 
 from ..cli import pass_ctx
+from ..validators import validate_identifier
 
 
 # Statistics stored on GenomicWindow nodes vs Variant nodes
@@ -41,6 +42,11 @@ def export_bed(ctx, stat, threshold, population, pop2, chromosome,
       graphpop export-bed --stat xpehh --threshold 3.0 --pop EUR --pop2 AFR -o xpehh.bed
       graphpop export-bed --stat tajima_d --threshold -2.0 --pop GJ-tmp -o tajimad.bed
     """
+    # Validate identifiers used in dynamic property names
+    validate_identifier(population, "population")
+    if pop2:
+        validate_identifier(pop2, "population")
+
     if stat == "xpehh" and not pop2:
         click.echo("Error: --pop2 is required for xpehh.", err=True)
         raise SystemExit(1)

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/export_windows.py

@@ -1,8 +1,6 @@
 """graphpop export-windows — batch export GenomicWindow nodes to TSV."""
 from __future__ import annotations
 
-from pathlib import Path
-
 import click
 
 from ..cli import pass_ctx

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/filter_results.py

@@ -5,6 +5,7 @@ import click
 
 from ..cli import pass_ctx
 from ..formatters import format_output
+from ..validators import validate_identifier
 
 
 @click.command("filter")
@@ -44,6 +45,11 @@ def filter_results(ctx, statistic, chr, population, output_path, fmt,
       graphpop filter nsl chr1 GJ-tmp --gene GW5 --min-score 2.0
       graphpop filter h12 chr1 GJ-tmp --consequence missense_variant
     """
+    # Validate identifiers used in dynamic property names
+    validate_identifier(population, "population")
+    if pop2:
+        validate_identifier(pop2, "population")
+
     # Build the property name for this statistic
     if statistic == "xpehh" and pop2:
         prop = f"xpehh_{population}_{pop2}"

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/plot.py

@@ -8,6 +8,7 @@ from pathlib import Path
 import click
 
 from ..cli import pass_ctx
+from ..validators import validate_identifier
 
 try:
     import matplotlib
@@ -827,10 +828,15 @@ def chromosome(ctx, chrom, population, stats, output, title, width, height):
     _check_matplotlib()
     _apply_style()
 
+    # Validate identifiers used in dynamic property names
+    validate_identifier(population, "population")
+
     stat_list = [s.strip() for s in stats.split(",") if s.strip()]
     if not stat_list:
         click.echo("No statistics specified.", err=True)
         raise SystemExit(1)
+    for s in stat_list:
+        validate_identifier(s, "statistic")
 
     window_stats = {"fst", "pi", "theta_w", "tajima_d"}
     variant_stats = {"ihs", "xpehh"}

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/rank_genes.py

@@ -5,6 +5,7 @@ import click
 
 from ..cli import pass_ctx
 from ..formatters import format_output
+from ..validators import validate_identifier
 
 
 @click.command("rank-genes")
@@ -38,6 +39,11 @@ def rank_genes(ctx, population, pop2, chromosome, top, sort_by,
       graphpop rank-genes --pop GJ-tmp --pop2 GJ-trop --chr Chr01 --sort-by max_abs_ihs
       graphpop rank-genes --pop EUR --pop2 AFR --sort-by mean_fst --format json
     """
+    # Validate identifiers used in dynamic property names
+    population = validate_identifier(population, "population")
+    if pop2:
+        pop2 = validate_identifier(pop2, "population")
+
     # Dynamic property names cannot be parameterized — kept as f-strings.
     ihs_prop = f"ihs_{population}"
     xpehh_prop = f"xpehh_{population}_{pop2}" if pop2 else None

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli/commands/setup.py

@@ -1,8 +1,9 @@
 """graphpop setup — download, configure, and initialize Neo4j for GraphPop."""
 from __future__ import annotations
 
-import platform
+import re
 import shutil
+import socket
 import subprocess
 import tarfile
 from pathlib import Path
@@ -13,11 +14,14 @@ import yaml
 
 
 DEFAULT_NEO4J_HOME = Path.home() / "neo4j"
-NEO4J_VERSION = "5.26.0"
+NEO4J_VERSION = "2025.12.1"
 NEO4J_DOWNLOAD_URL = (
     f"https://dist.neo4j.org/neo4j-community-{NEO4J_VERSION}-unix.tar.gz"
 )
 
+DEFAULT_BOLT_PORT = 7687
+DEFAULT_HTTP_PORT = 7474
+
 # GraphPop procedures plugin — auto-downloaded from GitHub Releases
 GRAPHPOP_PROCEDURES_VERSION = "0.1.0"
 GRAPHPOP_JAR_NAME = f"graphpop-procedures-{GRAPHPOP_PROCEDURES_VERSION}.jar"
@@ -27,6 +31,26 @@ GRAPHPOP_JAR_URL = (
 )
 
 
+def _port_in_use(port: int) -> int | None:
+    """Return the PID using *port*, or None if the port is free."""
+    try:
+        result = subprocess.run(
+            ["lsof", "-ti", f":{port}"],
+            capture_output=True, text=True,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return int(result.stdout.strip().splitlines()[0])
+    except (FileNotFoundError, ValueError):
+        pass
+    # Fallback: try to bind
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", port))
+        return None
+    except OSError:
+        return 0  # port in use but PID unknown
+
+
 @click.command()
 @click.option("--neo4j-home", type=click.Path(), default=str(DEFAULT_NEO4J_HOME),
               help=f"Neo4j installation directory (default: {DEFAULT_NEO4J_HOME})")
@@ -43,8 +67,18 @@ GRAPHPOP_JAR_URL = (
               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")
+@click.option("--bolt-port", type=int, default=DEFAULT_BOLT_PORT,
+              help=f"Bolt protocol port (default: {DEFAULT_BOLT_PORT})")
+@click.option("--http-port", type=int, default=DEFAULT_HTTP_PORT,
+              help=f"HTTP port for Neo4j Browser (default: {DEFAULT_HTTP_PORT})")
+@click.option("--neo4j-tarball", type=click.Path(exists=True), default=None,
+              help="Path to a local Neo4j tarball (skips download, for offline install)")
+@click.option("--adopt", is_flag=True,
+              help="Adopt a running Neo4j instance (deploys plugin and restarts)")
+@click.option("--yes", is_flag=True,
+              help="Skip interactive confirmations (use with --adopt)")
 def setup(neo4j_home, pagecache, heap, password, skip_download, deploy_plugin,
-          skip_plugin):
+          skip_plugin, bolt_port, http_port, neo4j_tarball, adopt, yes):
     """Set up Neo4j for GraphPop.
 
     Downloads Neo4j Community Edition, automatically downloads and deploys
@@ -60,20 +94,88 @@ def setup(neo4j_home, pagecache, heap, password, skip_download, deploy_plugin,
       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
+      graphpop setup --bolt-port 7688 --http-port 7475 --password mypass
+      graphpop setup --neo4j-tarball /path/to/neo4j.tar.gz --password mypass
+      graphpop setup --adopt --neo4j-home /path/to/neo4j --password mypass
     """
     neo4j_path = Path(neo4j_home)
 
     # Step 0: Check Java runtime
     _check_java()
 
+    # Step 0b: Check port conflicts
+    if not adopt:
+        pid = _port_in_use(bolt_port)
+        if pid is not None:
+            pid_str = f" (PID {pid})" if pid else ""
+            click.echo(
+                f"Error: Bolt port {bolt_port} is already in use{pid_str}.\n"
+                f"\n"
+                f"Options:\n"
+                f"  1. Stop the existing process"
+                + (f":  kill {pid}" if pid else "") + "\n"
+                f"  2. Install on different ports:\n"
+                f"     graphpop setup --bolt-port {bolt_port + 1} "
+                f"--http-port {http_port + 1} ...\n"
+                f"  3. Adopt the running instance:\n"
+                f"     graphpop setup --adopt --neo4j-home <neo4j-home> ...",
+                err=True,
+            )
+            raise SystemExit(1)
+
+    # --adopt path: deploy plugin to a running instance and restart
+    if adopt:
+        click.echo(f"Adopting existing Neo4j at {neo4j_path}...")
+        neo4j_bin = neo4j_path / "bin" / "neo4j"
+        if not neo4j_bin.exists():
+            click.echo(f"Error: Neo4j not found at {neo4j_path}", err=True)
+            raise SystemExit(1)
+
+        if not yes:
+            click.confirm(
+                "This will stop and restart the Neo4j instance. Continue?",
+                abort=True,
+            )
+
+        # Stop Neo4j
+        click.echo("Stopping Neo4j...")
+        subprocess.run([str(neo4j_bin), "stop"], capture_output=True, text=True)
+
+        # Deploy plugin
+        _deploy_plugin_to(neo4j_path, deploy_plugin, skip_plugin)
+
+        # Configure ports if non-default
+        if bolt_port != DEFAULT_BOLT_PORT or http_port != DEFAULT_HTTP_PORT:
+            click.echo("Configuring custom ports...")
+            _configure_neo4j(neo4j_path, pagecache, heap,
+                             bolt_port=bolt_port, http_port=http_port)
+        else:
+            click.echo("\nConfiguring Neo4j...")
+            _configure_neo4j(neo4j_path, pagecache, heap,
+                             bolt_port=bolt_port, http_port=http_port)
+
+        # Restart Neo4j
+        click.echo("Restarting Neo4j...")
+        subprocess.run([str(neo4j_bin), "start"], capture_output=True, text=True)
+
+        # Write config and summary
+        config_path = _write_config(neo4j_path, password, bolt_port)
+        _print_summary(neo4j_path, pagecache, heap, bolt_port, http_port,
+                       config_path, deploy_plugin, skip_plugin)
+        return
+
     # Step 1: Download Neo4j
-    if not skip_download:
+    if neo4j_tarball:
+        # Offline install: extract user-provided tarball
+        _extract_tarball(Path(neo4j_tarball), neo4j_path)
+        skip_download = True
+    elif 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:
+    if not skip_download and not neo4j_tarball:
         _download_neo4j(neo4j_path)
 
     # Verify installation
@@ -85,40 +187,56 @@ def setup(neo4j_home, pagecache, heap, password, skip_download, deploy_plugin,
 
     # Step 2: Configure Neo4j
     click.echo("\nConfiguring Neo4j...")
-    _configure_neo4j(neo4j_path, pagecache, heap)
+    _configure_neo4j(neo4j_path, pagecache, heap,
+                     bolt_port=bolt_port, http_port=http_port)
 
     # 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
+    _deploy_plugin_to(neo4j_path, deploy_plugin, skip_plugin)
+
+    # Step 5: Create GraphPop config
+    config_path = _write_config(neo4j_path, password, bolt_port)
+
+    # Step 6: Summary
+    _print_summary(neo4j_path, pagecache, heap, bolt_port, http_port,
+                   config_path, deploy_plugin, skip_plugin)
+
+
+def _deploy_plugin_to(neo4j_path: Path, deploy_plugin: str | None,
+                      skip_plugin: bool):
+    """Deploy the GraphPop procedures JAR to the Neo4j plugins directory."""
     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...")
+            click.echo("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}...")
+            click.echo(
+                f"Downloading GraphPop procedures plugin "
+                f"v{GRAPHPOP_PROCEDURES_VERSION}..."
+            )
             _download_plugin(plugin_dest)
             click.echo(f"  Deployed to {plugin_dest}")
 
-    # Step 5: Create GraphPop config
+
+def _write_config(neo4j_path: Path, password: str,
+                  bolt_port: int) -> Path:
+    """Write ~/.graphpop/config.yaml and return its path."""
     config_dir = Path.home() / ".graphpop"
     config_dir.mkdir(exist_ok=True)
     config_path = config_dir / "config.yaml"
 
     config = {
-        "uri": "bolt://localhost:7687",
+        "uri": f"bolt://localhost:{bolt_port}",
         "user": "neo4j",
         "password": password,
         "database": "neo4j",
@@ -127,14 +245,24 @@ def setup(neo4j_home, pagecache, heap, password, skip_download, deploy_plugin,
     with open(config_path, "w") as f:
         yaml.dump(config, f, default_flow_style=False)
     click.echo(f"\nGraphPop config written to {config_path}")
+    return config_path
+
+
+def _print_summary(neo4j_path: Path, pagecache: str, heap: str,
+                   bolt_port: int, http_port: int,
+                   config_path: Path, deploy_plugin: str | None,
+                   skip_plugin: bool):
+    """Print the post-setup summary."""
+    port_note = ""
+    if bolt_port != DEFAULT_BOLT_PORT or http_port != DEFAULT_HTTP_PORT:
+        port_note = f"\n  Bolt port:   {bolt_port}\n  HTTP port:   {http_port}"
 
-    # Step 6: Summary
     click.echo(f"""
 Setup complete!
 
   Neo4j home:    {neo4j_path}
   Page cache:    {pagecache}
-  Heap:          {heap}
+  Heap:          {heap}{port_note}
   Config:        {config_path}
   Plugin:        {'deployed' if (deploy_plugin or not skip_plugin) else 'not deployed (use --deploy-plugin or remove --skip-plugin)'}
 
@@ -143,6 +271,7 @@ Next steps:
   graphpop import --vcf data.vcf.gz \\
     --panel panel.txt --database mydb    # Import data
   graphpop diversity chr1 1 50000000 POP # Run analysis
+  graphpop doctor                        # Verify installation health
 """)
 
 
@@ -173,8 +302,36 @@ def _download_neo4j(dest: Path):
     click.echo(f"  Installed to {dest}")
 
 
-def _configure_neo4j(neo4j_home: Path, pagecache: str, heap: str):
-    """Configure Neo4j memory and settings."""
+def _extract_tarball(tarball_path: Path, dest: Path):
+    """Extract a user-provided Neo4j tarball for offline install."""
+    # Validate filename pattern
+    name = tarball_path.name
+    if not re.match(r"neo4j-community-[\d.]+(-unix)?\.tar\.gz", name):
+        click.echo(
+            f"Warning: tarball filename '{name}' does not match expected pattern "
+            f"'neo4j-community-5.x.y-unix.tar.gz'.",
+            err=True,
+        )
+
+    click.echo(f"Extracting {tarball_path} to {dest}...")
+    if dest.exists():
+        shutil.rmtree(dest)
+
+    with tarfile.open(tarball_path) as tf:
+        tf.extractall(dest.parent)
+
+    # Find the extracted directory (neo4j-community-X.Y.Z)
+    for child in dest.parent.iterdir():
+        if child.is_dir() and child.name.startswith("neo4j-community-") and child != dest:
+            child.rename(dest)
+            break
+    click.echo(f"  Installed to {dest}")
+
+
+def _configure_neo4j(neo4j_home: Path, pagecache: str, heap: str, *,
+                     bolt_port: int = DEFAULT_BOLT_PORT,
+                     http_port: int = DEFAULT_HTTP_PORT):
+    """Configure Neo4j memory, port, and security settings."""
     conf_path = neo4j_home / "conf" / "neo4j.conf"
 
     # Read existing config
@@ -190,6 +347,12 @@ def _configure_neo4j(neo4j_home: Path, pagecache: str, heap: str):
         "dbms.security.procedures.unrestricted": "graphpop.*",
     }
 
+    # Add port settings if non-default
+    if bolt_port != DEFAULT_BOLT_PORT:
+        settings["server.bolt.listen_address"] = f":{bolt_port}"
+    if http_port != DEFAULT_HTTP_PORT:
+        settings["server.http.listen_address"] = f":{http_port}"
+
     # Update or append settings
     updated_keys = set()
     new_lines = []
@@ -224,10 +387,10 @@ def _check_java():
         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",
+                f"  Warning: Java 21+ is required by Neo4j. "
+                f"Found version {m.group(1)}.\n"
+                f"  Install via: conda install -c conda-forge openjdk=21\n"
+                f"  Or: sudo apt install openjdk-21-jre-headless",
                 err=True,
             )
     except FileNotFoundError:

graphpop_cli-0.1.1/src/graphpop_cli/validators.py

@@ -0,0 +1,22 @@
+"""Shared validation utilities for GraphPop CLI commands."""
+from __future__ import annotations
+
+import re
+
+import click
+
+_IDENT_RE = re.compile(r'^[A-Za-z0-9_-]+$')
+
+
+def validate_identifier(value: str, label: str = "identifier") -> str:
+    """Validate that a value is safe for use as a Cypher property name.
+
+    Only alphanumeric characters, hyphens, and underscores are allowed.
+    Raises click.BadParameter if the value contains unsafe characters.
+    """
+    if not _IDENT_RE.match(value):
+        raise click.BadParameter(
+            f"Invalid {label}: {value!r}. Only alphanumeric, hyphen, "
+            "and underscore characters are allowed."
+        )
+    return value

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphpop-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Graph database-native population genomics CLI with O(V*K) complexity
 Author: Jianfeng Mao
 License: MIT

{graphpop_cli-0.1.0 → graphpop_cli-0.1.1}/src/graphpop_cli.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/graphpop_cli/cli.py
 src/graphpop_cli/config.py
 src/graphpop_cli/connection.py
 src/graphpop_cli/formatters.py
+src/graphpop_cli/validators.py
 src/graphpop_cli.egg-info/PKG-INFO
 src/graphpop_cli.egg-info/SOURCES.txt
 src/graphpop_cli.egg-info/dependency_links.txt
@@ -20,6 +21,7 @@ src/graphpop_cli/commands/converge.py
 src/graphpop_cli/commands/db.py
 src/graphpop_cli/commands/divergence.py
 src/graphpop_cli/commands/diversity.py
+src/graphpop_cli/commands/doctor.py
 src/graphpop_cli/commands/dump.py
 src/graphpop_cli/commands/export_bed.py
 src/graphpop_cli/commands/export_windows.py