feat: saar extract --index -- one-command OCI bootstrap (OPE-173)

The current setup path took 2+ hours of debugging (OPE-166). This makes
it one flag on a command the user already runs.

  saar extract ./my-repo --index

Flow:
  1. Check ~/.saar/config.yaml for OCI API key
  2. If no key: show how to get one, exit gracefully
  3. Detect git remote URL (SSH -> HTTPS conversion automatic)
  4. POST /api/v1/repos -- add repo to OCI
  5. POST /api/v1/repos/{id}/index -- trigger indexing with progress
  6. Save repo_id to .saar/config.json for future MCP use
  7. Extract always completes -- OCI failure is non-fatal

New module: saar/oci_client.py
- load/save ~/.saar/config.yaml (oci_api_key, oci_base_url)
- get_api_key() / get_base_url() with defaults
- detect_git_url(): SSH -> HTTPS conversion, graceful on failure
- detect_default_branch(): reads HEAD, falls back to 'main'
- add_repository() / poll_until_indexed(): clean HTTP wrappers
- save_repo_id() / load_repo_id(): .saar/config.json integration
- OCIAuthError / OCIAPIError: clean error hierarchy

saar/cli.py:
- --index flag on extract command
- _run_oci_indexing() helper: all OCI logic isolated, never breaks extract

Added tests/test_oci_client.py with 25 tests:
- Config read/write (round-trip, comments, corrupt file)
- Repo ID persistence (save/load, preserves existing fields)
- Git URL detection (SSH conversion, HTTPS passthrough, failure modes)
- Branch detection (success, failure fallback)
- CLI: no key shows guidance, OCI failure doesn't break extract,
  no git remote shows guidance, happy path shows indexed count,
  repo_id saved on success

Author: DevanshuNEU

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "saar"
-version = "0.3.6"
+version = "0.3.7"
 description = "Extract the essence of your codebase. Auto-generate AGENTS.md, CLAUDE.md, .cursorrules and more."
 readme = "README.md"
 license = "MIT"

saar/__init__.py

@@ -1,3 +1,3 @@
 """Saar -- extract the essence of your codebase."""
 
-__version__ = "0.3.6"
+__version__ = "0.3.7"

saar/cli.py

@@ -320,6 +320,11 @@ def extract(
         help="Max lines in generated file (default 100). 0 = unlimited. --verbose overrides to 0.",
         min=0,
     ),
+    index: bool = typer.Option(
+        False,
+        "--index",
+        help="After extraction, index this repo into OCI for AI-powered semantic search via MCP. Requires OCI API key in ~/.saar/config.yaml.",
+    ),
 ) -> None:
     """Analyze a codebase and extract its architectural DNA."""
     log_level = logging.DEBUG if verbose else logging.WARNING
@@ -410,6 +415,10 @@ def extract(
     except Exception:
         pass  # snapshot failure must never break extract
 
+    # -- optional OCI indexing (--index flag) --
+    if index:
+        _run_oci_indexing(repo_path, console)
+
     console.print("[bold green]done[/bold green]")
 
 
@@ -611,3 +620,103 @@ def _write_with_markers(
 
     target.write_text(before + wrapped + after, encoding="utf-8")
     console.print(f"  [green]updated[/green] {target} (preserved manual edits)")
+
+
+def _run_oci_indexing(repo_path: Path, console) -> None:
+    """Handle the --index flag: add repo to OCI and trigger indexing.
+
+    Fails gracefully -- a failure here must never prevent saar extract
+    from completing successfully. The AGENTS.md has already been written.
+    """
+    from saar.oci_client import (
+        get_api_key, get_base_url,
+        detect_git_url, detect_default_branch,
+        add_repository, poll_until_indexed,
+        save_repo_id, load_repo_id,
+        OCIAuthError, OCIAPIError,
+    )
+
+    console.print()
+    console.print("[bold]OCI indexing[/bold]")
+
+    # -- check for API key --
+    api_key = get_api_key()
+    if not api_key:
+        console.print(
+            "  [yellow]No OCI API key found.[/yellow]\n"
+            "  1. Go to [link=https://opencodeintel.com/dashboard/api-keys]opencodeintel.com/dashboard/api-keys[/link]\n"
+            "  2. Generate a key and save it:\n"
+            "     [dim]echo 'oci_api_key: ci_your_key_here' >> ~/.saar/config.yaml[/dim]\n"
+            "  3. Re-run with [bold]--index[/bold]"
+        )
+        return
+
+    base_url = get_base_url()
+
+    # -- detect git URL --
+    git_url = detect_git_url(repo_path)
+    if not git_url:
+        console.print(
+            "  [yellow]Could not detect git remote URL.[/yellow]\n"
+            "  Make sure this repo has an 'origin' remote:\n"
+            "  [dim]git remote add origin https://github.com/you/your-repo.git[/dim]"
+        )
+        return
+
+    branch = detect_default_branch(repo_path)
+    repo_name = repo_path.name
+
+    console.print(f"  repo:   [cyan]{git_url}[/cyan]")
+    console.print(f"  branch: [cyan]{branch}[/cyan]")
+
+    try:
+        # Check if already indexed -- avoid duplicate repos
+        existing_repo_id = load_repo_id(repo_path)
+        if existing_repo_id:
+            console.print(f"  [dim]Already in OCI (repo_id: {existing_repo_id[:8]}...). Re-indexing...[/dim]")
+            repo_id = existing_repo_id
+        else:
+            # Add repo
+            console.print("  Adding to OCI...")
+            repo = add_repository(
+                name=repo_name,
+                git_url=git_url,
+                branch=branch,
+                api_key=api_key,
+                base_url=base_url,
+            )
+            repo_id = repo.get("id") or repo.get("repo_id")
+            if not repo_id:
+                raise OCIAPIError("No repo_id returned from API")
+            save_repo_id(repo_path, repo_id)
+            console.print(f"  [green]Added[/green] (id: {repo_id[:8]}...)")
+
+        # Trigger indexing
+        console.print("  Indexing...")
+
+        def on_tick(elapsed: int, status: str) -> None:
+            console.print(f"  [dim]  {elapsed}s -- {status}...[/dim]", end="\r")
+
+        result = poll_until_indexed(
+            repo_id=repo_id,
+            api_key=api_key,
+            base_url=base_url,
+            on_tick=on_tick,
+        )
+
+        functions = result.get("total_functions") or result.get("function_count", 0)
+        console.print(f"\n  [green]Indexed[/green] {functions:,} functions")
+        console.print(
+            "  [dim]Use codeintel:search_code in Claude Desktop / Claude Code "
+            "to query this repo via MCP.[/dim]"
+        )
+
+    except OCIAuthError as e:
+        console.print(f"  [red]Auth error:[/red] {e}")
+        console.print("  Get a new key at [link=https://opencodeintel.com/dashboard/api-keys]opencodeintel.com/dashboard/api-keys[/link]")
+    except OCIAPIError as e:
+        console.print(f"  [yellow]OCI indexing skipped:[/yellow] {e}")
+        console.print("  AGENTS.md was still generated successfully.")
+    except Exception as e:
+        console.print(f"  [yellow]OCI indexing skipped:[/yellow] {e}")
+        console.print("  AGENTS.md was still generated successfully.")