ravmem-cli 0.1.0__py3-none-any.whl

ravmem/cli/main.py

@@ -0,0 +1,96 @@
+"""CLI entry point — registers all subcommands."""
+
+import logging
+from typing import Optional
+
+import typer
+
+
+def setup_logging(verbose: bool = False) -> None:
+    """Configure root logger based on verbosity or RAVMEM_LOG_LEVEL env var."""
+    import os
+    env_level = os.environ.get("RAVMEM_LOG_LEVEL", "").upper()
+    if verbose:
+        level = logging.DEBUG
+    elif env_level in ("DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"):
+        level = getattr(logging, env_level)
+    else:
+        level = logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+    )
+
+
+def version_callback(value: bool):
+    if value:
+        typer.echo("RavMem CLI v0.2.0")
+        raise typer.Exit()
+
+
+BANNER = r"""
+[bold cyan]
+  _____                        __  __                      
+ |  __ \                      |  \/  |                     
+ | |__) | __ ___   ___ __ ___ | \  / | ___ _ __ ___  
+ |  _  / / _` \ \ / / '_ ` _ \| |\/| |/ _ \ '_ ` _ \ 
+ | | \ \ (_| |\ V /| | | | | | |  | |  __/ | | | | |
+ |_|  \_\__,_| \_/ |_| |_| |_|_|  |_|\___|_| |_| |_|
+[/bold cyan]
+[bold]Persistent Memory & Context Engine for AI Agent Teams[/bold]
+"""
+
+app = typer.Typer(
+    name="ravmem",
+    help="RavMem — code knowledge graph engine",
+    rich_markup_mode="rich",
+)
+
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Enable debug logging"),
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-V", help="Show version and exit", callback=version_callback, is_eager=True
+    ),
+):
+    """
+    RavMem — The Code Knowledge Graph Engine.
+    """
+    setup_logging(verbose)
+    if ctx.invoked_subcommand is None and not version:
+        from rich.console import Console
+        Console().print(BANNER)
+        typer.echo(ctx.get_help())
+
+from ravmem.cli.analyze import analyze_cmd
+from ravmem.cli.auth import app as auth_app
+from ravmem.cli.config_cmd import app as config_app
+from ravmem.cli.impact import impact_cmd
+from ravmem.cli.kg import app as kg_app
+from ravmem.cli.remote import app as remote_app
+from ravmem.cli.search import search_cmd
+from ravmem.cli.serve import serve_cmd
+from ravmem.cli.info import health_cmd, metrics_cmd
+from ravmem.cli.diff import diff_impact_cmd
+from ravmem.cli.browse import clusters_cmd, symbols_cmd
+
+app.command("analyze")(analyze_cmd)
+app.command("search")(search_cmd)
+app.command("impact")(impact_cmd)
+app.command("serve")(serve_cmd)
+app.command("health")(health_cmd)
+app.command("metrics")(metrics_cmd)
+app.command("diff-impact")(diff_impact_cmd)
+app.command("clusters")(clusters_cmd)
+app.command("symbols")(symbols_cmd)
+app.add_typer(auth_app, name="auth")
+app.add_typer(config_app, name="config")
+app.add_typer(remote_app, name="remote")
+app.add_typer(kg_app, name="kg")
+
+
+if __name__ == "__main__":
+    app()

ravmem/cli/remote.py

@@ -0,0 +1,549 @@
+"""ravmem remote — manage a remote RavMem server."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import typer
+from rich.table import Table
+
+app = typer.Typer(
+    name="remote",
+    help="Manage remote RavMem server",
+    no_args_is_help=True,
+)
+
+
+def _console():
+    """Lazy import of rich console."""
+    from rich.console import Console
+
+    return Console()
+
+
+def _get_client():
+    """Build a client from saved config or exit with an error."""
+    from ravmem.client.config import get_client_from_config
+
+    client = get_client_from_config()
+    if client is None:
+        typer.echo(
+            "Remote server not configured. Run 'ravmem remote config --url <URL>' first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return client
+
+
+def _resolve_project(explicit: str | None) -> str:
+    """Return *explicit* if given, else fall back to config default_project."""
+    if explicit:
+        return explicit
+    from ravmem.client.config import load_config
+
+    cfg = load_config()
+    proj = cfg.get("default_project", "")
+    if not proj:
+        typer.echo(
+            "No --project given and no default_project configured. "
+            "Run 'ravmem remote use <project_id>' to set a default.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return proj
+
+
+def _resolve_branch(explicit: str | None) -> str:
+    """Return *explicit* if given, else fall back to config default_branch."""
+    if explicit:
+        return explicit
+    from ravmem.client.config import load_config
+
+    cfg = load_config()
+    return cfg.get("default_branch", "") or "main"
+
+
+# ------------------------------------------------------------------
+# Commands
+# ------------------------------------------------------------------
+
+
+@app.command("config")
+def config_cmd(
+    url: Optional[str] = typer.Option(None, "--url", help="Server URL"),
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="API key"),
+) -> None:
+    """Configure server connection. Saved to ~/.ravmem/client.json"""
+    from ravmem.client.config import load_config, save_config
+
+    cfg = load_config()
+    if url is not None:
+        cfg["server_url"] = url.rstrip("/")
+    if api_key is not None:
+        cfg["api_key"] = api_key
+    save_config(cfg)
+    typer.echo("Configuration saved.")
+    typer.echo(f"  server_url: {cfg['server_url']}")
+    typer.echo(f"  api_key:    {'***' if cfg['api_key'] else '(none)'}")
+
+
+@app.command("projects")
+def projects_cmd(
+    output_json: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """List all projects on the server."""
+    client = _get_client()
+    try:
+        projects = client.list_projects()
+    finally:
+        client.close()
+
+    if output_json:
+        import json
+        typer.echo(json.dumps(projects, indent=2, default=str))
+        return
+
+    if not projects:
+        typer.echo("No projects found.")
+        return
+
+    table = Table(title="Projects")
+    table.add_column("ID", style="cyan")
+    table.add_column("Name")
+    table.add_column("Default Branch")
+    table.add_column("Repo")
+    for p in projects:
+        table.add_row(
+            p.get("id", ""),
+            p.get("name", ""),
+            p.get("default_branch", ""),
+            p.get("repo_url", "") or p.get("repo_path", ""),
+        )
+    _console().print(table)
+
+
+@app.command("add")
+def add_cmd(
+    path: Optional[str] = typer.Argument(
+        None,
+        help="Local path to the repo (upload mode) or server path (mount mode). "
+             "Omit when using --git-url.",
+    ),
+    name: Optional[str] = typer.Option(None, "--name", help="Project display name"),
+    default_branch: str = typer.Option(
+        "main", "--default-branch",
+        help="Primary branch (used as base for new-branch copy-from-base optimisation)",
+    ),
+    # Clone mode
+    git_url: Optional[str] = typer.Option(
+        None, "--git-url",
+        help="Git remote URL — server clones this. Selects clone mode.",
+    ),
+    git_username: Optional[str] = typer.Option(
+        None, "--git-username",
+        help="Git username for private repos (clone mode only).",
+    ),
+    git_token: Optional[str] = typer.Option(
+        None, "--git-token",
+        help="Git token/password for private repos (clone mode only). "
+             "Stored encrypted on the server — never logged.",
+        hide_input=True,
+    ),
+    # Mount mode
+    mount: bool = typer.Option(
+        False, "--mount",
+        help="Mount mode: treat PATH as a volume already mounted on the server. "
+             "No file upload; admin keeps the mount current.",
+    ),
+) -> None:
+    """Register a project on the remote server.
+
+    \b
+    Three modes — pick exactly one:
+
+      Upload (default when PATH is given):
+        ravmem remote add /local/repo --name myproject
+
+      Clone from public GitHub/GitLab:
+        ravmem remote add --git-url https://github.com/org/repo --name myproject
+
+      Clone from private repo:
+        ravmem remote add --git-url https://github.com/org/private \\
+                          --git-username myuser --git-token ghp_xxx --name myproject
+
+      Mount (server-side volume / symlink):
+        ravmem remote add /mounted/repo --name myproject --mount
+    """
+    if not git_url and not path:
+        typer.echo(
+            "✗ Specify a source:\n"
+            "  Upload:  ravmem remote add <PATH>\n"
+            "  Clone:   ravmem remote add --git-url <URL>\n"
+            "  Mount:   ravmem remote add <PATH> --mount",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    client = _get_client()
+    try:
+        result = client.create_project(
+            git_url=git_url,
+            git_username=git_username,
+            git_token=git_token,
+            repo_path=path,
+            mount=mount,
+            name=name,
+            default_branch=default_branch,
+        )
+    finally:
+        client.close()
+
+    mode = result.get("index_mode", "upload")
+    typer.echo(f"✓ Project created: {result.get('id', '')}")
+    typer.echo(f"  name:           {result.get('name', '')}")
+    typer.echo(f"  mode:           {mode}")
+    typer.echo(f"  default branch: {result.get('default_branch', '')}")
+    if mode == "upload":
+        typer.echo(
+            "\n  Next: run 'ravmem analyze <PATH> --project "
+            + result.get("id", "<id>")
+            + "' to upload and index."
+        )
+    elif mode == "clone":
+        typer.echo(
+            "\n  Next: run 'ravmem analyze --project "
+            + result.get("id", "<id>")
+            + "' to trigger the first index."
+        )
+
+
+@app.command("use")
+def use_cmd(
+    project_id: str = typer.Argument(..., help="Project ID to set as default"),
+) -> None:
+    """Set the default project for remote commands."""
+    from ravmem.client.config import load_config, save_config
+
+    cfg = load_config()
+    cfg["default_project"] = project_id
+    save_config(cfg)
+    typer.echo(f"Default project set to '{project_id}'.")
+
+
+@app.command("branches")
+def branches_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    output_json: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """List branches and their index status."""
+    project_id = _resolve_project(project)
+    client = _get_client()
+    try:
+        branches = client.list_branches(project_id)
+    finally:
+        client.close()
+
+    if output_json:
+        import json
+        typer.echo(json.dumps(branches, indent=2, default=str))
+        return
+
+    if not branches:
+        typer.echo("No branches indexed.")
+        return
+
+    table = Table(title=f"Branches for {project_id}")
+    table.add_column("Branch", style="cyan")
+    table.add_column("Status")
+    table.add_column("Symbols")
+    table.add_column("Last Indexed")
+    for b in branches:
+        table.add_row(
+            b.get("branch", ""),
+            b.get("status", ""),
+            str(b.get("symbol_count", "")),
+            b.get("last_indexed", ""),
+        )
+    _console().print(table)
+
+
+@app.command("index")
+def index_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    branch: Optional[str] = typer.Option(None, "--branch", "-b", help="Branch to index"),
+    mode: str = typer.Option("auto", "--mode", help="Index mode: full, incremental, auto"),
+    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for indexing to complete"),
+) -> None:
+    """Trigger indexing on the remote server."""
+    project_id = _resolve_project(project)
+    branch_name = _resolve_branch(branch)
+    client = _get_client()
+    try:
+        result = client.index_branch(project_id, branch_name, mode=mode)
+        job_id = result.get("job_id")
+        typer.echo(f"Indexing started: job_id={job_id}")
+
+        if wait and job_id is not None:
+            typer.echo("Waiting for completion...")
+            job = client.poll_job(job_id)
+            status = job.get("status", "unknown")
+            typer.echo(f"Job {job_id} finished: {status}")
+            if status == "failed":
+                typer.echo(f"  reason: {job.get('failure_reason', 'unknown')}", err=True)
+    finally:
+        client.close()
+
+
+@app.command("delete")
+def delete_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    branch: Optional[str] = typer.Option(None, "--branch", "-b",
+        help="Branch name — if given, deletes only that branch index (not the whole project)"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Delete a project or a single branch index from the server."""
+    client = _get_client()
+    project_id = _resolve_project(project)
+    try:
+        if branch:
+            if not yes:
+                typer.confirm(
+                    f"Delete branch index '{branch}' in project '{project_id}'?", abort=True
+                )
+            result = client.delete_branch_index(project_id, branch)
+            typer.echo(f"Branch index '{branch}' deleted from project '{project_id}'.")
+        else:
+            if not yes:
+                typer.confirm(
+                    f"Delete project '{project_id}' and ALL its indexes? This cannot be undone.",
+                    abort=True,
+                )
+            result = client.delete_project(project_id)
+            typer.echo(f"Project '{project_id}' deleted.")
+    finally:
+        client.close()
+
+
+@app.command("status")
+def status_cmd(
+    job_id: Optional[int] = typer.Option(None, "--job-id", "-j", help="Job ID to check"),
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    branch: Optional[str] = typer.Option(None, "--branch", "-b", help="Branch name"),
+    output_json: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    """Check indexing job or branch index status."""
+    client = _get_client()
+    try:
+        if job_id is not None:
+            job = client.get_job(job_id)
+            if output_json:
+                import json
+                typer.echo(json.dumps(job, indent=2, default=str))
+                return
+            typer.echo(f"Job {job_id}:")
+            typer.echo(f"  status:   {job.get('status', '')}")
+            typer.echo(f"  started:  {job.get('started_at', '')}")
+            typer.echo(f"  finished: {job.get('ended_at', '')}")
+            if job.get("failure_reason"):
+                typer.echo(f"  reason:   {job['failure_reason']}")
+            return
+
+        project_id = _resolve_project(project)
+        branch_name = _resolve_branch(branch)
+        info = client.get_branch_status(project_id, branch_name)
+
+        if output_json:
+            import json
+            typer.echo(json.dumps(info, indent=2, default=str))
+            return
+
+        status = info.get("status", "unknown")
+        index_mode = info.get("index_mode", "mount")
+        last_commit = info.get("last_indexed_commit") or ""
+        commit_msg = info.get("last_indexed_commit_message") or ""
+        indexed_at = info.get("last_indexed_at") or ""
+        symbol_count = info.get("symbol_count", 0)
+        edge_count = info.get("edge_count", 0)
+        parent_branch = info.get("parent_branch") or ""
+        parent_commit = info.get("parent_last_indexed_commit") or ""
+        active_job = info.get("active_job")
+
+        commit_display = f"{last_commit[:7]}  \"{commit_msg}\"" if last_commit else "(none)"
+        parent_display = (
+            f"{parent_branch}  (indexed at {parent_commit[:7]})"
+            if parent_branch and parent_commit
+            else parent_branch or "(none)"
+        )
+
+        col = 24
+        typer.echo(f"{'Branch:':<{col}}{branch_name}")
+        typer.echo(f"{'Status:':<{col}}{status}")
+        typer.echo(f"{'Index mode:':<{col}}{index_mode}")
+        typer.echo(f"{'Last indexed commit:':<{col}}{commit_display}")
+        typer.echo(f"{'Last indexed at:':<{col}}{indexed_at or '(never)'}")
+        typer.echo(f"{'Symbols:':<{col}}{symbol_count:,}")
+        typer.echo(f"{'Edges:':<{col}}{edge_count:,}")
+        typer.echo(f"{'Parent branch:':<{col}}{parent_display}")
+
+        if active_job:
+            jid = active_job.get("id", "?")
+            jstatus = active_job.get("status", "")
+            phase = active_job.get("current_phase", "")
+            pct = active_job.get("progress_pct", 0)
+            typer.echo(f"\nActive job #{jid}: {jstatus}  phase={phase}  {pct}%")
+
+        if status == "failed":
+            typer.echo("\nWarning: last indexing run failed.", err=True)
+        elif status == "stale":
+            typer.echo("\nNote: index may be out of date — run `ravmem analyze` to refresh.")
+    finally:
+        client.close()
+
+
+@app.command("sync")
+def sync_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+) -> None:
+    """Fetch the latest remote commits into the server-side workspace (clone-mode only).
+
+    This pulls new commits from the remote without re-indexing.
+    Run `ravmem analyze --project <id>` afterwards to index the new changes.
+    """
+    client = _get_client()
+    try:
+        project_id = _resolve_project(project)
+        typer.echo(f"Syncing workspace for project '{project_id}'…")
+        result = client.sync_workspace(project_id)
+
+        duration_s = result.get("duration_ms", 0) / 1000
+        fetched_branches = result.get("fetched_branches", [])
+        fetched_commits = result.get("fetched_commits", 0)
+        head = result.get("workspace_head", "")
+
+        head_display = f" (workspace @ {head})" if head else ""
+        commits_display = f"{fetched_commits} commit{'s' if fetched_commits != 1 else ''} fetched"
+        branches_display = (
+            f", {len(fetched_branches)} new branch{'es' if len(fetched_branches) != 1 else ''}"
+            f" ({', '.join(fetched_branches)})"
+            if fetched_branches else ""
+        )
+
+        typer.echo(
+            f"✓ Synced in {duration_s:.1f}s — {commits_display}"
+            f"{branches_display}{head_display}"
+        )
+        if fetched_commits > 0 or fetched_branches:
+            typer.echo(
+                "  Run `ravmem analyze --project <id>` to index the new changes."
+            )
+        else:
+            typer.echo("  Already up to date.")
+    except Exception as exc:
+        typer.echo(f"✗ Sync failed: {exc}", err=True)
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+
+@app.command("reset-workspace")
+def reset_workspace_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Delete the server-side workspace and reset all branch index records.
+
+    Valid for clone and upload mode projects.  The workspace directory is
+    removed and all branch statuses are set to 'empty', so the next
+    `ravmem analyze` or clone will start from scratch.
+
+    Mount-mode projects cannot be reset — their workspace is managed externally.
+    """
+    client = _get_client()
+    try:
+        project_id = _resolve_project(project)
+        if not yes:
+            typer.confirm(
+                f"Reset workspace for project '{project_id}'? "
+                "This removes the server-side checkout and clears all branch indexes.",
+                abort=True,
+            )
+        result = client.reset_workspace(project_id)
+
+        branches_cleared = result.get("branches_cleared", 0)
+        removed = result.get("removed_workspace", False)
+        typer.echo(f"✓ Workspace reset for project '{project_id}'.")
+        if removed:
+            typer.echo("  Workspace directory removed.")
+        typer.echo(f"  {branches_cleared} branch record{'s' if branches_cleared != 1 else ''} cleared.")
+        typer.echo(
+            "  Next: run `ravmem analyze --project <id>` (upload) or "
+            "`ravmem analyze --project <id>` (clone) to re-index."
+        )
+    except typer.Abort:
+        typer.echo("Aborted.")
+    except Exception as exc:
+        typer.echo(f"✗ Reset failed: {exc}", err=True)
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+
+@app.command("set-credentials")
+def set_credentials_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    git_username: Optional[str] = typer.Option(None, "--git-username", help="Git username"),
+    git_token: Optional[str] = typer.Option(
+        None, "--git-token", help="Git token/password (stored encrypted on server)",
+        hide_input=True,
+    ),
+) -> None:
+    """Store or replace encrypted git credentials for a clone-mode project.
+
+    Credentials are encrypted server-side (requires RAVMEM_SECRET_KEY on the server).
+    Use this to update credentials after rotating a token without re-registering the project.
+    """
+    project_id = _resolve_project(project)
+    if not git_username:
+        git_username = typer.prompt("Git username")
+    if not git_token:
+        git_token = typer.prompt("Git token/password", hide_input=True)
+    client = _get_client()
+    try:
+        client.set_credentials(project_id, git_username, git_token)
+        typer.echo(f"✓ Credentials stored for project '{project_id}'.")
+        typer.echo("  Token is encrypted at rest. Run `ravmem analyze` to use the updated credentials.")
+    except Exception as exc:
+        typer.echo(f"✗ Failed to store credentials: {exc}", err=True)
+        raise typer.Exit(1)
+    finally:
+        client.close()
+
+
+@app.command("delete-credentials")
+def delete_credentials_cmd(
+    project: Optional[str] = typer.Option(None, "--project", "-p", help="Project ID"),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
+) -> None:
+    """Remove stored git credentials from a clone-mode project.
+
+    The project will revert to unauthenticated cloning (public repos only).
+    """
+    project_id = _resolve_project(project)
+    if not yes:
+        typer.confirm(
+            f"Remove stored credentials for project '{project_id}'?", abort=True
+        )
+    client = _get_client()
+    try:
+        result = client.delete_credentials(project_id)
+        if result.get("deleted"):
+            typer.echo(f"✓ Credentials deleted for project '{project_id}'.")
+        else:
+            typer.echo(f"  No credentials were stored for project '{project_id}'.")
+    except typer.Abort:
+        typer.echo("Aborted.")
+    except Exception as exc:
+        typer.echo(f"✗ Failed to delete credentials: {exc}", err=True)
+        raise typer.Exit(1)
+    finally:
+        client.close()