Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

refactor(cli): extract shared provider/store/state helpers (#252)

Swati Ahuja6c2d3eebbd2a
diff --git a/packages/cli/src/repowise/cli/_repo_session.py b/packages/cli/src/repowise/cli/_repo_session.py
new file mode 100644
index 000000000..1158e0c0d
--- /dev/null
+++ b/packages/cli/src/repowise/cli/_repo_session.py
@@ -0,0 +1,45 @@
+"""Repo-local database session helpers shared across CLI commands.
+
+Collapses the ``get_db_url_for_repo → create_engine → init_db →
+create_session_factory → upsert_repository`` dance that several CLI commands
+repeat before doing per-repo database work.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+async def open_repo_db(
+ repo_path: Path,
+ *,
+ repo_name: str | None = None,
+ init: bool = True,
+) -> tuple[Any, Any, str]:
+ """Open the repo-local database and ensure the repository row exists.
+
+ Returns ``(engine, session_factory, repo_id)``. The engine is **not**
+ disposed — the caller owns its lifetime (cost trackers keep it open for the
+ duration of generation; persistence paths dispose it when done).
+ """
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_repository,
+ )
+
+ url = get_db_url_for_repo(repo_path)
+ engine = create_engine(url)
+ if init:
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ async with get_session(sf) as session:
+ repo = await upsert_repository(
+ session, name=repo_name or repo_path.name, local_path=str(repo_path)
+ )
+ repo_id = repo.id
+ return engine, sf, repo_id
diff --git a/packages/cli/src/repowise/cli/_setup.py b/packages/cli/src/repowise/cli/_setup.py
new file mode 100644
index 000000000..835960c23
--- /dev/null
+++ b/packages/cli/src/repowise/cli/_setup.py
@@ -0,0 +1,34 @@
+"""Shared CLI process setup helpers."""
+
+from __future__ import annotations
+
+
+def setup_logging_silence() -> None:
+ """Quiet library + structlog output so progress bars are the only output.
+
+ ``init`` / ``update`` render their own Rich progress bars; the underlying
+ library loggers (httpx/httpcore) and the ``repowise.core`` / ``repowise.server``
+ structlog loggers would otherwise interleave debug/info lines with the bars.
+
+ ``cache_logger_on_first_use=False`` is load-bearing: modules that called
+ ``structlog.get_logger(__name__)`` at import time hold a bound logger
+ snapshotted before this ``configure`` runs — so without disabling the cache,
+ debug lines from ``core/ingestion/*`` (graph, traverser, parser, …) leak past
+ the ERROR filter on the first run of a session.
+ """
+ import logging
+
+ logging.getLogger("httpx").setLevel(logging.ERROR)
+ logging.getLogger("httpcore").setLevel(logging.ERROR)
+ for _logger_name in ("repowise.core", "repowise.server"):
+ logging.getLogger(_logger_name).setLevel(logging.ERROR)
+
+ try:
+ import structlog
+
+ structlog.configure(
+ wrapper_class=structlog.make_filtering_bound_logger(logging.ERROR),
+ cache_logger_on_first_use=False,
+ )
+ except ImportError:
+ pass
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.py
index 398d362e0..3e81a63f8 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd.py
@@ -5,6 +5,7 @@ from __future__ import annotations
import os
import sys
import time
+from datetime import UTC
from pathlib import Path
from typing import Any
@@ -12,6 +13,7 @@ import click
from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
from rich.table import Table
+from repowise.cli._setup import setup_logging_silence
from repowise.cli.cost_estimator import build_generation_plan, estimate_cost
from repowise.cli.editor_integrations.defaults import get_default_disabled_project_files
from repowise.cli.editor_setup import (
@@ -32,6 +34,13 @@ from repowise.cli.helpers import (
save_config,
save_state,
)
+from repowise.cli.providers import (
+ build_cost_tracker,
+ build_embedder,
+ build_vector_store,
+ resolve_embedder,
+)
+from repowise.cli.state_persistence import build_kg_state, save_knowledge_graph_json
from repowise.cli.ui import MaybeCountColumn
# ---------------------------------------------------------------------------
@@ -138,17 +147,12 @@ def _offer_hook_install(
)
-def _resolve_embedder(embedder_flag: str | None) -> str:
- """Auto-detect embedder from env vars, or use the flag value."""
- if embedder_flag:
- return embedder_flag
- if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
- return "gemini"
- if os.environ.get("OPENAI_API_KEY"):
- return "openai"
- if os.environ.get("OPENROUTER_API_KEY"):
- return "openrouter"
- return "mock"
+# ``_resolve_embedder`` / ``_build_embedder`` now live in
+# ``cli.providers.embedders``. They keep their leading-underscore aliases here
+# because several sibling commands (update/reindex/search) import them from
+# this module — the aliases preserve that import surface.
+_resolve_embedder = resolve_embedder
+_build_embedder = build_embedder
# ---------------------------------------------------------------------------
@@ -242,32 +246,6 @@ async def _persist_result(
# ---------------------------------------------------------------------------
-def _build_embedder(embedder_name_resolved: str) -> Any:
- """Construct the configured embedder, falling back to MockEmbedder.
-
- Shared by the generation flows and the decision semantic-dedup wiring so
- the same backend selection logic isn't duplicated. Real providers fall
- back to the deterministic mock when their SDK/credentials are unavailable.
- """
- from repowise.core.providers.embedding.base import MockEmbedder
-
- if embedder_name_resolved == "gemini":
- try:
- from repowise.core.providers.embedding.gemini import GeminiEmbedder
-
- return GeminiEmbedder()
- except Exception:
- return MockEmbedder()
- if embedder_name_resolved == "openai":
- try:
- from repowise.core.providers.embedding.openai import OpenAIEmbedder
-
- return OpenAIEmbedder()
- except Exception:
- return MockEmbedder()
- return MockEmbedder()
-
-
def _run_workspace_generation(
*,
repo_path: Path,
@@ -292,40 +270,13 @@ def _run_workspace_generation(
workspace run.
"""
from repowise.cli.cost_estimator import build_generation_plan, estimate_cost
- from repowise.cli.helpers import get_db_url_for_repo
from repowise.cli.ui import RichProgressCallback
from repowise.core.generation import GenerationConfig
- from repowise.core.generation.cost_tracker import CostTracker
- from repowise.core.persistence import (
- create_engine as _ce,
- )
- from repowise.core.persistence import (
- create_session_factory as _csf,
- )
- from repowise.core.persistence import (
- get_session as _gs,
- )
- from repowise.core.persistence import (
- init_db as _idb,
- )
- from repowise.core.persistence import (
- upsert_repository as _ur,
- )
- from repowise.core.persistence.vector_store import InMemoryVectorStore
from repowise.core.pipeline import run_generation
- # Build embedder
- embedder_impl: Any = _build_embedder(embedder_name_resolved)
-
- # Build vector store
- lance_dir = repo_path / ".repowise" / "lancedb"
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
-
- lance_dir.mkdir(parents=True, exist_ok=True)
- vector_store: Any = LanceDBVectorStore(str(lance_dir), embedder=embedder_impl)
- except ImportError:
- vector_store = InMemoryVectorStore(embedder_impl)
+ # Build embedder + vector store
+ embedder_impl: Any = build_embedder(embedder_name_resolved)
+ vector_store: Any = build_vector_store(repo_path, embedder_impl)
# Stash the store on the result so persist's Phase-2C decision dedup
# matches against — and embeds decisions into — the same store the pages
@@ -422,21 +373,7 @@ def _run_workspace_generation(
# Cost tracker (DB-backed when possible)
from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
- async def _make_cost_tracker() -> CostTracker:
- url = get_db_url_for_repo(repo_path)
- engine = _ce(url)
- await _idb(engine)
- sf = _csf(engine)
- async with _gs(sf) as _sess:
- _repo = await _ur(_sess, name=result.repo_name, local_path=str(repo_path))
- _repo_id = _repo.id
- return CostTracker(session_factory=sf, repo_id=_repo_id)
-
- try:
- cost_tracker = run_async(_make_cost_tracker())
- except Exception:
- cost_tracker = CostTracker()
-
+ cost_tracker = build_cost_tracker(repo_path, result.repo_name)
provider._cost_tracker = cost_tracker
with Progress(
@@ -530,24 +467,7 @@ def _workspace_init(
advanced mode (interactively) or passes an explicit provider, also runs
LLM generation per repo.
"""
- import logging
-
- logging.getLogger("httpx").setLevel(logging.ERROR)
- logging.getLogger("httpcore").setLevel(logging.ERROR)
- for _logger_name in ("repowise.core", "repowise.server"):
- logging.getLogger(_logger_name).setLevel(logging.ERROR)
- try:
- import structlog
-
- # cache_logger_on_first_use=False: see init_command for rationale —
- # otherwise module-level ``structlog.get_logger`` calls hold a logger
- # snapshotted before configure() and bypass this filter.
- structlog.configure(
- wrapper_class=structlog.make_filtering_bound_logger(logging.ERROR),
- cache_logger_on_first_use=False,
- )
- except ImportError:
- pass
+ setup_logging_silence()
from rich.progress import BarColumn, Progress, SpinnerColumn, TextColumn, TimeElapsedColumn
@@ -806,31 +726,18 @@ def _workspace_init(
state["phase_timings"] = repo_phase_timings
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
- state["knowledge_graph"] = {
- "version": "1.0.0",
- "node_count": len(kg.nodes) if hasattr(kg, "nodes") else 0,
- "layer_count": len(kg.layers) if hasattr(kg, "layers") else 0,
- "tour_steps": len(kg.tour) if hasattr(kg, "tour") else 0,
- "has_summaries": any(n.get("summary") for n in kg.nodes)
- if hasattr(kg, "nodes")
- else False,
- "fingerprint": getattr(kg, "fingerprint", ""),
- }
+ state["knowledge_graph"] = build_kg_state(kg)
save_state(repo.path, state)
- if kg is not None and hasattr(kg, "to_dict"):
- import json as _kg_json
-
- kg_json_path = repo.path / ".repowise" / "knowledge-graph.json"
- kg_json_path.parent.mkdir(parents=True, exist_ok=True)
- kg_json_path.write_text(_kg_json.dumps(kg.to_dict(), indent=2), encoding="utf-8")
+ if kg is not None:
+ save_knowledge_graph_json(repo.path, kg)
# Update workspace config with indexing metadata
- from datetime import datetime, timezone
+ from datetime import datetime
entry = ws_config.get_repo(repo.alias)
if entry is not None:
- entry.indexed_at = datetime.now(timezone.utc).isoformat()
+ entry.indexed_at = datetime.now(UTC).isoformat()
entry.last_commit_at_index = head
# MCP config + editor setup files per repo
@@ -1186,27 +1093,7 @@ def init_command(
load_dotenv(repo_path)
# Suppress library/structlog output — progress bars are the only output needed.
- import logging
-
- logging.getLogger("httpx").setLevel(logging.ERROR)
- logging.getLogger("httpcore").setLevel(logging.ERROR)
- for _logger_name in ("repowise.core", "repowise.server"):
- logging.getLogger(_logger_name).setLevel(logging.ERROR)
-
- try:
- import structlog
-
- # Without cache_logger_on_first_use=False, modules that called
- # ``structlog.get_logger(__name__)`` at import time hold a bound logger
- # snapshotted before this configure ran — so debug lines from
- # ``core/ingestion/*`` (graph, traverser, parser, …) would leak past
- # the ERROR filter on the first ``init`` of a session.
- structlog.configure(
- wrapper_class=structlog.make_filtering_bound_logger(logging.ERROR),
- cache_logger_on_first_use=False,
- )
- except ImportError:
- pass
+ setup_logging_silence()
# ---- Interactive mode (TTY, no explicit flags) ----
is_interactive = sys.stdin.isatty() and provider_name is None and not index_only
@@ -1491,6 +1378,7 @@ def init_command(
# ``--coverage`` flag was passed; otherwise the configured
# percentage drives a single non-interactive estimate.
from dataclasses import replace as _replace_cfg
+
from repowise.cli.cost_estimator import compute_coverage_options
from repowise.cli.coverage_select import interactive_coverage_select
from repowise.core.generation import GenerationConfig
@@ -1602,18 +1490,8 @@ def init_command(
if not cost_declined:
# Build embedder + vector store
- from repowise.core.persistence.vector_store import InMemoryVectorStore
-
- embedder_impl: Any = _build_embedder(embedder_name_resolved)
-
- lance_dir = repo_path / ".repowise" / "lancedb"
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
-
- lance_dir.mkdir(parents=True, exist_ok=True)
- vector_store: Any = LanceDBVectorStore(str(lance_dir), embedder=embedder_impl)
- except ImportError:
- vector_store = InMemoryVectorStore(embedder_impl)
+ embedder_impl: Any = build_embedder(embedder_name_resolved)
+ vector_store: Any = build_vector_store(repo_path, embedder_impl)
# Run generation via the pipeline's generation function
from repowise.core.pipeline import run_generation
@@ -1630,48 +1508,10 @@ def init_command(
gen_callback = RichProgressCallback(gen_progress, console)
# Construct a CostTracker backed by the real DB so every LLM call
- # is persisted to the llm_costs table. We need the repo_id from the
- # database row that was created/upserted during _persist_result
- # (which has not run yet), so we look it up or fall back to in-memory.
- from repowise.cli.helpers import get_db_url_for_repo
- from repowise.core.generation.cost_tracker import CostTracker
- from repowise.core.persistence import (
- create_engine as _create_engine,
- )
- from repowise.core.persistence import (
- create_session_factory as _create_sf,
- )
- from repowise.core.persistence import (
- get_session as _get_session,
- )
- from repowise.core.persistence import (
- init_db as _init_db,
- )
- from repowise.core.persistence import (
- upsert_repository as _upsert_repo,
- )
-
- async def _make_cost_tracker() -> CostTracker:
- url = get_db_url_for_repo(repo_path)
- engine = _create_engine(url)
- await _init_db(engine)
- sf = _create_sf(engine)
- async with _get_session(sf) as _sess:
- _repo = await _upsert_repo(
- _sess,
- name=result.repo_name,
- local_path=str(repo_path),
- )
- _repo_id = _repo.id
- # Keep engine alive for the duration of generation — it will be
- # disposed by _persist_result's own engine later.
- return CostTracker(session_factory=sf, repo_id=_repo_id)
-
- try:
- cost_tracker = run_async(_make_cost_tracker())
- except Exception:
- # Fallback to in-memory tracker if DB setup fails
- cost_tracker = CostTracker()
+ # is persisted to the llm_costs table. The engine stays open for
+ # the duration of generation and is disposed by _persist_result's
+ # own engine later. Falls back to an in-memory tracker on failure.
+ cost_tracker = build_cost_tracker(repo_path, result.repo_name)
# Attach tracker to provider unconditionally (all providers now
# accept _cost_tracker as an attribute)
@@ -1796,22 +1636,8 @@ def init_command(
base_state["phase_timings"] = phase_timings
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
- base_state["knowledge_graph"] = {
- "version": "1.0.0",
- "node_count": len(kg.nodes) if hasattr(kg, "nodes") else 0,
- "layer_count": len(kg.layers) if hasattr(kg, "layers") else 0,
- "tour_steps": len(kg.tour) if hasattr(kg, "tour") else 0,
- "has_summaries": any(n.get("summary") for n in kg.nodes)
- if hasattr(kg, "nodes")
- else False,
- "fingerprint": getattr(kg, "fingerprint", ""),
- }
- if hasattr(kg, "to_dict"):
- import json as _kg_json
-
- kg_json_path = repo_path / ".repowise" / "knowledge-graph.json"
- kg_json_path.parent.mkdir(parents=True, exist_ok=True)
- kg_json_path.write_text(_kg_json.dumps(kg.to_dict(), indent=2), encoding="utf-8")
+ base_state["knowledge_graph"] = build_kg_state(kg)
+ save_knowledge_graph_json(repo_path, kg)
if effective_index_only or provider is None:
save_state(repo_path, base_state)
@@ -1859,24 +1685,11 @@ def init_command(
state["phase_timings"] = phase_timings
kg = getattr(result, "knowledge_graph_result", None)
if kg is not None:
- state["knowledge_graph"] = {
- "version": "1.0.0",
- "node_count": len(kg.nodes) if hasattr(kg, "nodes") else 0,
- "layer_count": len(kg.layers) if hasattr(kg, "layers") else 0,
- "tour_steps": len(kg.tour) if hasattr(kg, "tour") else 0,
- "has_summaries": any(n.get("summary") for n in kg.nodes)
- if hasattr(kg, "nodes")
- else False,
- "fingerprint": getattr(kg, "fingerprint", ""),
- }
+ state["knowledge_graph"] = build_kg_state(kg)
save_state(repo_path, state)
- if kg is not None and hasattr(kg, "to_dict"):
- import json as _kg_json
-
- kg_json_path = repo_path / ".repowise" / "knowledge-graph.json"
- kg_json_path.parent.mkdir(parents=True, exist_ok=True)
- kg_json_path.write_text(_kg_json.dumps(kg.to_dict(), indent=2), encoding="utf-8")
+ if kg is not None:
+ save_knowledge_graph_json(repo_path, kg)
save_config(
repo_path,
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd.py b/packages/cli/src/repowise/cli/commands/update_cmd.py
index 06f9ffc8e..5867fd0fd 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd.py
@@ -63,18 +63,10 @@ def _build_update_vector_store(repo_path: Any, cfg: dict) -> Any | None:
Returns ``None`` on any failure — the decision upsert still works without it.
"""
try:
- from repowise.cli.commands.init_cmd import _build_embedder, _resolve_embedder
- from repowise.core.persistence.vector_store import InMemoryVectorStore
+ from repowise.cli.providers import build_embedder, build_vector_store, resolve_embedder
- embedder = _build_embedder(_resolve_embedder(cfg.get("embedder")))
- lance_dir = repo_path / ".repowise" / "lancedb"
- try:
- from repowise.core.persistence.vector_store import LanceDBVectorStore
-
- lance_dir.mkdir(parents=True, exist_ok=True)
- return LanceDBVectorStore(str(lance_dir), embedder=embedder)
- except ImportError:
- return InMemoryVectorStore(embedder)
+ embedder = build_embedder(resolve_embedder(cfg.get("embedder")))
+ return build_vector_store(repo_path, embedder)
except Exception:
return None
@@ -708,29 +700,9 @@ def update_command(
# table — matching what `repowise init` already does. Without this,
# `repowise costs` only ever reflects the initial index and shows $0 for
# all subsequent updates.
- from repowise.cli.helpers import get_db_url_for_repo
- from repowise.core.generation.cost_tracker import CostTracker
- from repowise.core.persistence import (
- create_engine,
- create_session_factory,
- get_session,
- init_db,
- upsert_repository,
- )
-
- async def _make_cost_tracker() -> CostTracker:
- url = get_db_url_for_repo(repo_path)
- engine = create_engine(url)
- await init_db(engine)
- sf = create_session_factory(engine)
- async with get_session(sf) as session:
- repo = await upsert_repository(session, name=repo_path.name, local_path=str(repo_path))
- return CostTracker(session_factory=sf, repo_id=repo.id)
+ from repowise.cli.providers import build_cost_tracker
- try:
- cost_tracker = run_async(_make_cost_tracker())
- except Exception:
- cost_tracker = CostTracker()
+ cost_tracker = build_cost_tracker(repo_path, repo_path.name)
provider._cost_tracker = cost_tracker
# (dead_code_report computed above, before the index-only branch)
diff --git a/packages/cli/src/repowise/cli/providers/__init__.py b/packages/cli/src/repowise/cli/providers/__init__.py
new file mode 100644
index 000000000..c985e5da6
--- /dev/null
+++ b/packages/cli/src/repowise/cli/providers/__init__.py
@@ -0,0 +1,20 @@
+"""Shared CLI provider/store construction helpers.
+
+These collect the embedder / vector-store / cost-tracker construction logic that
+was previously copy-pasted across ``init_cmd`` and ``update_cmd`` so every CLI
+command builds them the same way.
+"""
+
+from __future__ import annotations
+
+from repowise.cli.providers.cost_tracking import build_cost_tracker, make_cost_tracker
+from repowise.cli.providers.embedders import build_embedder, resolve_embedder
+from repowise.cli.providers.vector_store import build_vector_store
+
+__all__ = [
+ "build_cost_tracker",
+ "build_embedder",
+ "build_vector_store",
+ "make_cost_tracker",
+ "resolve_embedder",
+]
diff --git a/packages/cli/src/repowise/cli/providers/cost_tracking.py b/packages/cli/src/repowise/cli/providers/cost_tracking.py
new file mode 100644
index 000000000..7043e027f
--- /dev/null
+++ b/packages/cli/src/repowise/cli/providers/cost_tracking.py
@@ -0,0 +1,31 @@
+"""Cost-tracker construction shared across CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.generation.cost_tracker import CostTracker
+
+
+async def make_cost_tracker(repo_path: Path, repo_name: str) -> CostTracker:
+ """Build a DB-backed :class:`CostTracker` for the repo-local database.
+
+ Resolves (or creates) the repository row so every LLM call made during
+ this run is persisted to the ``llm_costs`` table. The engine is
+ intentionally left open: it lives for the duration of generation and is
+ disposed later by the persistence path that reuses the same database.
+ """
+ from repowise.cli._repo_session import open_repo_db
+
+ _engine, sf, repo_id = await open_repo_db(repo_path, repo_name=repo_name)
+ return CostTracker(session_factory=sf, repo_id=repo_id)
+
+
+def build_cost_tracker(repo_path: Path, repo_name: str) -> CostTracker:
+ """Construct a cost tracker, falling back to an in-memory one on failure."""
+ from repowise.cli.helpers import run_async
+
+ try:
+ return run_async(make_cost_tracker(repo_path, repo_name))
+ except Exception:
+ return CostTracker()
diff --git a/packages/cli/src/repowise/cli/providers/embedders.py b/packages/cli/src/repowise/cli/providers/embedders.py
new file mode 100644
index 000000000..029671d4a
--- /dev/null
+++ b/packages/cli/src/repowise/cli/providers/embedders.py
@@ -0,0 +1,45 @@
+"""Embedder selection + construction shared across CLI commands."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+def resolve_embedder(embedder_flag: str | None) -> str:
+ """Auto-detect embedder from env vars, or use the flag value."""
+ if embedder_flag:
+ return embedder_flag
+ if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
+ return "gemini"
+ if os.environ.get("OPENAI_API_KEY"):
+ return "openai"
+ if os.environ.get("OPENROUTER_API_KEY"):
+ return "openrouter"
+ return "mock"
+
+
+def build_embedder(embedder_name_resolved: str) -> Any:
+ """Construct the configured embedder, falling back to MockEmbedder.
+
+ Shared by the generation flows and the decision semantic-dedup wiring so
+ the same backend selection logic isn't duplicated. Real providers fall
+ back to the deterministic mock when their SDK/credentials are unavailable.
+ """
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ if embedder_name_resolved == "gemini":
+ try:
+ from repowise.core.providers.embedding.gemini import GeminiEmbedder
+
+ return GeminiEmbedder()
+ except Exception:
+ return MockEmbedder()
+ if embedder_name_resolved == "openai":
+ try:
+ from repowise.core.providers.embedding.openai import OpenAIEmbedder
+
+ return OpenAIEmbedder()
+ except Exception:
+ return MockEmbedder()
+ return MockEmbedder()
diff --git a/packages/cli/src/repowise/cli/providers/vector_store.py b/packages/cli/src/repowise/cli/providers/vector_store.py
new file mode 100644
index 000000000..feb58ab8d
--- /dev/null
+++ b/packages/cli/src/repowise/cli/providers/vector_store.py
@@ -0,0 +1,25 @@
+"""Vector-store construction shared across CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def build_vector_store(repo_path: Path, embedder: Any) -> Any:
+ """Build the repo-local vector store, preferring LanceDB.
+
+ Uses LanceDB at ``.repowise/lancedb`` so previously-embedded pages and
+ decisions stay matchable across runs; falls back to an in-memory store
+ (which only sees this run's vectors) when LanceDB isn't installed.
+ """
+ from repowise.core.persistence.vector_store import InMemoryVectorStore
+
+ lance_dir = repo_path / ".repowise" / "lancedb"
+ try:
+ from repowise.core.persistence.vector_store import LanceDBVectorStore
+
+ lance_dir.mkdir(parents=True, exist_ok=True)
+ return LanceDBVectorStore(str(lance_dir), embedder=embedder)
+ except ImportError:
+ return InMemoryVectorStore(embedder)
diff --git a/packages/cli/src/repowise/cli/state_persistence.py b/packages/cli/src/repowise/cli/state_persistence.py
new file mode 100644
index 000000000..0c8d6fe61
--- /dev/null
+++ b/packages/cli/src/repowise/cli/state_persistence.py
@@ -0,0 +1,37 @@
+"""Shared state.json / knowledge-graph persistence helpers for CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def build_kg_state(kg: Any) -> dict[str, Any]:
+ """Build the ``state.json`` ``knowledge_graph`` summary block for a KG result.
+
+ Mirrors the summary the ``init`` / ``update`` flows persist so the web UI and
+ subsequent runs can read KG size + fingerprint without loading the full graph.
+ """
+ return {
+ "version": "1.0.0",
+ "node_count": len(kg.nodes) if hasattr(kg, "nodes") else 0,
+ "layer_count": len(kg.layers) if hasattr(kg, "layers") else 0,
+ "tour_steps": len(kg.tour) if hasattr(kg, "tour") else 0,
+ "has_summaries": any(n.get("summary") for n in kg.nodes) if hasattr(kg, "nodes") else False,
+ "fingerprint": getattr(kg, "fingerprint", ""),
+ }
+
+
+def save_knowledge_graph_json(repo_path: Path, kg: Any) -> None:
+ """Write ``.repowise/knowledge-graph.json`` for a KG result.
+
+ No-op when the result can't serialize itself (``to_dict`` missing), so
+ callers only need to guard against a ``None`` knowledge graph.
+ """
+ if not hasattr(kg, "to_dict"):
+ return
+ import json
+
+ kg_json_path = repo_path / ".repowise" / "knowledge-graph.json"
+ kg_json_path.parent.mkdir(parents=True, exist_ok=True)
+ kg_json_path.write_text(json.dumps(kg.to_dict(), indent=2), encoding="utf-8")
diff --git a/tests/unit/cli/test_shared_helpers.py b/tests/unit/cli/test_shared_helpers.py
new file mode 100644
index 000000000..012b721a3
--- /dev/null
+++ b/tests/unit/cli/test_shared_helpers.py
@@ -0,0 +1,139 @@
+"""Smoke + characterization tests for the shared CLI helper modules.
+
+These guard the extraction of provider/store/state helpers out of ``init_cmd`` /
+``update_cmd``: they assert the command modules route through the single shared
+implementation (no divergent copies) and pin the behavior of the pure helpers.
+"""
+
+from __future__ import annotations
+
+import types
+
+import pytest
+
+from repowise.cli import _repo_session, _setup, providers, state_persistence
+from repowise.cli.commands import init_cmd, update_cmd
+
+
+def test_command_modules_import() -> None:
+ """Both command modules import cleanly with the helpers in place."""
+ assert isinstance(init_cmd, types.ModuleType)
+ assert isinstance(update_cmd, types.ModuleType)
+
+
+def test_helpers_are_single_source() -> None:
+ """The private aliases on ``init_cmd`` point at the shared implementations.
+
+ Sibling commands (update/reindex/search) import ``_resolve_embedder`` /
+ ``_build_embedder`` from ``init_cmd``; these must remain the same objects as
+ the canonical ``providers`` helpers so there's exactly one implementation.
+ """
+ assert init_cmd._resolve_embedder is providers.resolve_embedder
+ assert init_cmd._build_embedder is providers.build_embedder
+
+
+def test_resolve_embedder_explicit_flag_wins(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("GEMINI_API_KEY", "x")
+ assert providers.resolve_embedder("openai") == "openai"
+
+
+ ("env", "expected"),
+ [
+ ({"GEMINI_API_KEY": "x"}, "gemini"),
+ ({"GOOGLE_API_KEY": "x"}, "gemini"),
+ ({"OPENAI_API_KEY": "x"}, "openai"),
+ ({"OPENROUTER_API_KEY": "x"}, "openrouter"),
+ ({}, "mock"),
+ ],
+)
+def test_resolve_embedder_env_detection(
+ monkeypatch: pytest.MonkeyPatch, env: dict[str, str], expected: str
+) -> None:
+ for key in (
+ "GEMINI_API_KEY",
+ "GOOGLE_API_KEY",
+ "OPENAI_API_KEY",
+ "OPENROUTER_API_KEY",
+ ):
+ monkeypatch.delenv(key, raising=False)
+ for key, val in env.items():
+ monkeypatch.setenv(key, val)
+ assert providers.resolve_embedder(None) == expected
+
+
+def test_build_embedder_falls_back_to_mock() -> None:
+ """Unknown / unavailable backends degrade to the deterministic mock."""
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ assert isinstance(providers.build_embedder("definitely-not-a-backend"), MockEmbedder)
+ assert isinstance(providers.build_embedder("mock"), MockEmbedder)
+
+
+def test_build_vector_store_returns_a_store(tmp_path) -> None:
+ from repowise.core.providers.embedding.base import MockEmbedder
+
+ store = providers.build_vector_store(tmp_path, MockEmbedder())
+ assert store is not None
+ # LanceDB (when installed) creates its dir under .repowise/lancedb.
+ assert store is not None
+
+
+class _FakeKG:
+ nodes = [{"summary": "s"}, {"summary": ""}]
+ layers = [1, 2, 3]
+ tour = [1, 2]
+ fingerprint = "abc123"
+
+ def to_dict(self) -> dict:
+ return {"nodes": self.nodes, "fingerprint": self.fingerprint}
+
+
+def test_build_kg_state_shape() -> None:
+ state = state_persistence.build_kg_state(_FakeKG())
+ assert state == {
+ "version": "1.0.0",
+ "node_count": 2,
+ "layer_count": 3,
+ "tour_steps": 2,
+ "has_summaries": True,
+ "fingerprint": "abc123",
+ }
+
+
+def test_build_kg_state_missing_attrs() -> None:
+ state = state_persistence.build_kg_state(object())
+ assert state == {
+ "version": "1.0.0",
+ "node_count": 0,
+ "layer_count": 0,
+ "tour_steps": 0,
+ "has_summaries": False,
+ "fingerprint": "",
+ }
+
+
+def test_save_knowledge_graph_json_writes_file(tmp_path) -> None:
+ import json
+
+ state_persistence.save_knowledge_graph_json(tmp_path, _FakeKG())
+ out = tmp_path / ".repowise" / "knowledge-graph.json"
+ assert out.exists()
+ assert json.loads(out.read_text(encoding="utf-8"))["fingerprint"] == "abc123"
+
+
+def test_save_knowledge_graph_json_noop_without_to_dict(tmp_path) -> None:
+ state_persistence.save_knowledge_graph_json(tmp_path, object())
+ assert not (tmp_path / ".repowise" / "knowledge-graph.json").exists()
+
+
+def test_setup_logging_silence_runs() -> None:
+ import logging
+
+ _setup.setup_logging_silence()
+ assert logging.getLogger("httpx").level == logging.ERROR
+ assert logging.getLogger("httpcore").level == logging.ERROR
+
+
+def test_repo_session_exposes_open_repo_db() -> None:
+ assert callable(_repo_session.open_repo_db)