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.

fix: name keyless upgrade commands in init, status, and get_answer (#3143)

Aman925e44ad22df
diff --git a/docs/reference/MCP_RESPONSE_FIELDS.md b/docs/reference/MCP_RESPONSE_FIELDS.md
index 7123d197d..2ea8c9909 100644
--- a/docs/reference/MCP_RESPONSE_FIELDS.md
+++ b/docs/reference/MCP_RESPONSE_FIELDS.md
@@ -35,6 +35,7 @@ Routine responses carry a lean envelope. `get_overview`, called once per session
| `embedder_degraded` | When an embedder is resolved | `true` or `false` |
| `embedder`, `embedder_warning` | Only when the embedder fell back to a mock or degraded mode, or the semantic index on disk could not be opened | Which embedder, and why |
| `newer_release` | Once per server process | A newer repowise is published; restart the MCP server after upgrading |
+| `keyless_note` | Once per server process, on the first `get_answer` reply that degrades with `no-llm-provider` | Names what a model would add: `repowise generate` writes synthesized answers with a model (needs a key, or `--provider ollama` for a local model). Not repeated on later replies, and never sent when a provider is configured |
| `response_budget` | When the budget cut something or could not fit the protected fields (`enforcement_error`); always on `get_overview` | `limit_chars` (the ceiling), `tier` (`default` or `expanded`), `serialized_chars` (size delivered) |
| `omitted` | When content was cut | `refs`, `tokens`, `restore`. See [Truncation and recovery](#truncation-and-recovery) |
| `recovery_unavailable` | When the omission store could not be written | Names the storage failure; the cut rows cannot be restored |
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
index fb000d57b..2b188664f 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py
@@ -20,6 +20,7 @@ from repowise.cli.ui import (
build_contextual_next_steps,
build_status_notes,
format_elapsed,
+ keyless_upgrade_note,
print_analysis_summary,
print_files_written,
)
@@ -280,6 +281,13 @@ def show_completion(
" [dim]Every page is derived from structure and says so in its footer. "
f"{_search_note}[/dim]"
)
+ # A keyless index is finished, not partial — this just names the
+ # two upgrades available from here and the command for each, so
+ # the headless path (no editor setup, no `generate` row in
+ # build_contextual_next_steps) still learns about them (#3105).
+ console.print(
+ f" [dim]{keyless_upgrade_note(_scope['search']['semantic'] == 'available')}[/dim]"
+ )
_print_embed_failure(_embed_failed)
else:
console.print(
diff --git a/packages/cli/src/repowise/cli/commands/status_cmd.py b/packages/cli/src/repowise/cli/commands/status_cmd.py
index 7a4e24687..af6ee639d 100644
--- a/packages/cli/src/repowise/cli/commands/status_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/status_cmd.py
@@ -23,6 +23,7 @@ from repowise.cli.helpers import (
)
from repowise.cli.output import emit_json, format_option, notice_console
from repowise.cli.ui.brand import format_bytes
+from repowise.cli.ui.result_panels import keyless_upgrade_note
from repowise.core.docs_mode import resolve_docs_mode
from repowise.core.index_scope import resolve_index_scope
@@ -699,6 +700,15 @@ def status_command(path: str | None, workspace: bool, no_workspace: bool, fmt: s
state_table.add_row("Full upgrade", scope["upgrade"]["status"])
console.print(state_table)
+ # A template-only scope is a finished keyless index, not a broken one —
+ # name the upgrade commands here too, since "Full upgrade pending" above
+ # names no command on its own (#3105). Mirrors the init closing note.
+ if scope["content_provenance"] == "template":
+ note = keyless_upgrade_note(
+ scope["search"]["semantic"] == "available", scope["search"]["next_command"]
+ )
+ console.print(f"[dim]{note}[/dim]")
+
if not has_db:
console.print(f"[yellow]Database not found at {db_path}.[/yellow]")
return
diff --git a/packages/cli/src/repowise/cli/ui/__init__.py b/packages/cli/src/repowise/cli/ui/__init__.py
index 4def08d69..a7a97ce90 100644
--- a/packages/cli/src/repowise/cli/ui/__init__.py
+++ b/packages/cli/src/repowise/cli/ui/__init__.py
@@ -42,6 +42,7 @@ _LAZY: dict[str, str] = {
"build_completion_panel": "result_panels",
"build_contextual_next_steps": "result_panels",
"build_status_notes": "result_panels",
+ "keyless_upgrade_note": "result_panels",
"format_bytes": "brand",
"format_elapsed": "brand",
"interactive_advanced_config": "mode_selection",
diff --git a/packages/cli/src/repowise/cli/ui/result_panels.py b/packages/cli/src/repowise/cli/ui/result_panels.py
index cdc79f10e..bd99ad75a 100644
--- a/packages/cli/src/repowise/cli/ui/result_panels.py
+++ b/packages/cli/src/repowise/cli/ui/result_panels.py
@@ -190,6 +190,29 @@ def build_contextual_next_steps(
return steps
+def keyless_upgrade_note(semantic_available: bool, reindex_command: str | None = None) -> str:
+ """One sentence naming the upgrade commands a keyless index has left.
+
+ Shared verbatim between ``repowise init``'s closing note and ``repowise
+ status``'s template-only scope line (#3105), so the wording cannot drift
+ between the two surfaces. Plain wording, no counts or percentages, and
+ nothing implying the keyless index is unfinished or broken — it is a
+ complete index; this just names what more is available.
+
+ ``reindex_command`` lets a caller that has ``search.next_command`` from
+ the stamped scope use that exact command instead of the generic default,
+ so the note cannot name a flag combination the run did not actually need.
+ """
+ prose = (
+ "repowise generate writes the subsystem pages with a model "
+ "(needs a key, or --provider ollama for a local model)"
+ )
+ if semantic_available:
+ return f"{prose}."
+ command = reindex_command or "repowise reindex"
+ return f"{prose}; {command} adds semantic search."
+
+
def build_status_notes(setup: Any) -> list[str]:
"""Rich-markup notes about MCP and hook wiring, shown beside the panel.
diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.py
index cdc0906a2..96521f6c1 100644
--- a/packages/server/src/repowise/server/mcp_server/__init__.py
+++ b/packages/server/src/repowise/server/mcp_server/__init__.py
@@ -338,6 +338,7 @@ _STATE_NAMES = frozenset(
"_embedder_status",
"_release_check",
"_release_announced",
+ "_keyless_note_announced",
}
)
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
index cf5e0e820..aa329ad30 100644
--- a/packages/server/src/repowise/server/mcp_server/_meta.py
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -829,6 +829,28 @@ def _release_meta() -> dict[str, Any]:
}
+def keyless_note_meta() -> dict[str, Any]:
+ """Name what a key or a local model would add, once per process, the
+ first time ``get_answer`` degrades with ``no-llm-provider`` (#3105).
+
+ The agent reading a keyless answer is told synthesis is missing, but
+ nothing says how to get it. Same once-per-process shape as
+ :func:`_release_meta`: a fact the caller only needs once, not charged
+ against every later response's budget.
+ """
+ from repowise.server.mcp_server import _state
+
+ if _state._keyless_note_announced:
+ return {}
+ _state._keyless_note_announced = True
+ return {
+ "keyless_note": (
+ "repowise generate writes synthesized answers with a model "
+ "(needs a key, or --provider ollama for a local model)"
+ )
+ }
+
+
def symbol_hint(symbol_id: str, end_line: int, start_line: int) -> str | None:
"""Hint for source retrieval (kept for backward compat with tool_symbol.py)."""
return None
diff --git a/packages/server/src/repowise/server/mcp_server/_state.py b/packages/server/src/repowise/server/mcp_server/_state.py
index 2d3493171..ce426dc0d 100644
--- a/packages/server/src/repowise/server/mcp_server/_state.py
+++ b/packages/server/src/repowise/server/mcp_server/_state.py
@@ -72,3 +72,8 @@ _vector_store_errors: dict[str, str] = {}
# each newer release is surfaced once per process rather than on every call.
_release_check: Any = None
_release_announced: str | None = None
+
+# Whether ``get_answer``'s ``no-llm-provider`` degraded path has already named
+# what a key or local model would add in this process. Same once-per-process
+# shape as ``_release_announced``: a fact the caller only needs the first time.
+_keyless_note_announced: bool = False
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
index 2f45317e3..d80acb999 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer/degraded.py
@@ -12,6 +12,7 @@ import time
from repowise.server.mcp_server._meta import _normalize_target_path
from repowise.server.mcp_server._meta import answer_hint as _answer_hint
from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import keyless_note_meta as _keyless_note_meta
from repowise.server.mcp_server.tool_answer.bodies import (
_build_symbol_bodies,
_gather_body_candidates,
@@ -214,6 +215,7 @@ async def _degraded_payload(
targets=[*citations, *fallback_targets],
),
"degraded": reason,
+ **(_keyless_note_meta() if reason == "no-llm-provider" else {}),
}
return _with_candidates(payload, resolved_pool if resolved_pool is not None else hits)
diff --git a/tests/unit/cli/test_fast_mode_offer.py b/tests/unit/cli/test_fast_mode_offer.py
index cf3b1d1f6..c5e96380c 100644
--- a/tests/unit/cli/test_fast_mode_offer.py
+++ b/tests/unit/cli/test_fast_mode_offer.py
@@ -8,6 +8,7 @@ from repowise.cli.ui import (
RepoScanInfo,
build_contextual_next_steps,
build_status_notes,
+ keyless_upgrade_note,
should_offer_fast_mode,
)
@@ -195,3 +196,31 @@ def test_next_steps_render_without_truncation_or_collision():
out = console.export_text()
assert "repowise hook rewrite install" in out
assert "compress noisy command output" in out
+
+
+def test_keyless_upgrade_note_names_both_commands_by_default():
+ note = keyless_upgrade_note(semantic_available=False)
+ assert "repowise generate" in note
+ assert "--provider ollama" in note
+ assert "repowise reindex adds semantic search" in note
+ assert "..." not in note # a user must be able to copy-paste it
+
+
+def test_keyless_upgrade_note_omits_search_half_when_already_available():
+ note = keyless_upgrade_note(semantic_available=True)
+ assert "repowise generate" in note
+ assert "reindex" not in note
+ assert "embedder" not in note
+
+
+def test_keyless_upgrade_note_uses_the_scope_s_own_next_command():
+ note = keyless_upgrade_note(
+ semantic_available=False, reindex_command="repowise reindex --embedder ollama"
+ )
+ assert "repowise reindex --embedder ollama" in note
+
+
+def test_keyless_upgrade_note_falls_back_without_a_next_command():
+ note = keyless_upgrade_note(semantic_available=False, reindex_command=None)
+ assert "repowise reindex adds semantic search" in note
+ assert "..." not in note
diff --git a/tests/unit/cli/test_init_failure_reporting.py b/tests/unit/cli/test_init_failure_reporting.py
index 82e2fdf22..904d03d5b 100644
--- a/tests/unit/cli/test_init_failure_reporting.py
+++ b/tests/unit/cli/test_init_failure_reporting.py
@@ -547,3 +547,81 @@ def test_run_repo_generation_uses_exact_job_id_when_provided(tmp_path, monkeypat
)
assert getattr(result, "failed_page_ids", None) == ["file_page:target_failure.ts"]
+
+
+class TestInitClosingKeylessNote:
+ """A keyless index closes by naming its upgrade commands (#3105).
+
+ The note must not depend on editor setup: the headless path has no
+ ``generate`` row in the next-steps panel, so this line is the only place
+ it hears about the upgrades.
+ """
+
+ def _output(self, monkeypatch, *, setup, pages, state=None) -> str:
+ import io
+
+ from rich.console import Console
+
+ buf = io.StringIO()
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.reporting.console",
+ Console(file=buf, width=200, force_terminal=False),
+ )
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.reporting.build_completion_panel",
+ lambda title, metrics, next_steps=None: "PANEL",
+ )
+ monkeypatch.setattr(
+ "repowise.cli.commands.init_cmd.reporting.load_state",
+ lambda _p: state if state is not None else {"docs_mode": "deterministic"},
+ )
+ monkeypatch.setattr("repowise.cli.commands.init_cmd.reporting.load_config", lambda _p: {})
+ show_completion(
+ repo_path="/fake",
+ result=_completion_result(pages),
+ start=0.0,
+ effective_index_only=True,
+ run_mode="standard",
+ provider=SimpleNamespace(provider_name="template", model_name="template"),
+ setup=setup,
+ )
+ return buf.getvalue()
+
+ @pytest.mark.parametrize(
+ "setup",
+ [
+ None,
+ SimpleNamespace(editor_setup_disabled=True),
+ SimpleNamespace(
+ editor_setup_disabled=False,
+ claude_code_connected=True,
+ interactive=True,
+ first_index=True,
+ autosync_hook_installed=True,
+ rewrite_hook_installed=True,
+ ),
+ ],
+ ids=["no-setup", "editor-setup-disabled", "editor-setup-done"],
+ )
+ def test_note_prints_with_and_without_editor_setup(self, monkeypatch, setup):
+ out = self._output(monkeypatch, setup=setup, pages=[_page("file_page:a")])
+ assert "repowise generate writes the subsystem pages" in out
+ assert "--provider ollama" in out
+ assert "repowise reindex adds semantic search" in out
+ assert "--embedder ..." not in out
+
+ def test_note_drops_the_search_half_when_semantic_search_is_available(self, monkeypatch):
+ state = {
+ "docs_mode": "deterministic",
+ "index_scope": {
+ "content_provenance": "template",
+ "search": {"full_text": "available", "semantic": "available"},
+ },
+ }
+ out = self._output(monkeypatch, setup=None, pages=[_page("file_page:a")], state=state)
+ assert "repowise generate writes the subsystem pages" in out
+ assert "reindex" not in out
+
+ def test_no_note_when_fast_mode_rendered_no_pages(self, monkeypatch):
+ out = self._output(monkeypatch, setup=None, pages=[])
+ assert "repowise generate" not in out
diff --git a/tests/unit/cli/test_status_storage.py b/tests/unit/cli/test_status_storage.py
index 025c27e7f..31457b959 100644
--- a/tests/unit/cli/test_status_storage.py
+++ b/tests/unit/cli/test_status_storage.py
@@ -33,3 +33,51 @@ def test_health_line_for_a_repo_with_no_scored_file(monkeypatch) -> None:
)
line = status_cmd._query_health_line(Path("."))
assert line is not None and "not analysed" in line and "2992" in line
+
+
+class TestStatusKeylessUpgradeNote:
+ """``repowise status`` names the keyless upgrade commands, template-only (#3105)."""
+
+ def _status_output(self, monkeypatch, tmp_path: Path, state: dict) -> str:
+ import io
+
+ from click.testing import CliRunner
+ from rich.console import Console
+
+ (tmp_path / ".repowise").mkdir()
+ buf = io.StringIO()
+ monkeypatch.setattr(
+ status_cmd, "console", Console(file=buf, width=200, force_terminal=False)
+ )
+ monkeypatch.setattr(status_cmd, "load_state", lambda _p: state)
+ monkeypatch.setattr(status_cmd, "load_config", lambda _p: {})
+ monkeypatch.setattr(status_cmd, "db_configured", lambda: False)
+ result = CliRunner().invoke(status_cmd.status_command, [str(tmp_path), "--no-workspace"])
+ assert result.exit_code == 0, result.output
+ return buf.getvalue()
+
+ def test_template_only_scope_prints_the_note(self, monkeypatch, tmp_path) -> None:
+ out = self._status_output(monkeypatch, tmp_path, {"docs_mode": "deterministic"})
+ assert "repowise generate writes the subsystem pages" in out
+ assert "--provider ollama" in out
+
+ def test_note_uses_the_scopes_own_next_command(self, monkeypatch, tmp_path) -> None:
+ state = {
+ "docs_mode": "deterministic",
+ "index_scope": {
+ "content_provenance": "template",
+ "search": {
+ "full_text": "available",
+ "semantic": "unavailable",
+ "next_command": "repowise reindex",
+ },
+ },
+ }
+ out = self._status_output(monkeypatch, tmp_path, state)
+ assert "repowise reindex adds semantic search" in out
+ assert "--embedder ..." not in out
+
+ def test_model_backed_scope_does_not_print_it(self, monkeypatch, tmp_path) -> None:
+ out = self._status_output(monkeypatch, tmp_path, {"docs_mode": "llm"})
+ assert "Scope" in out
+ assert "repowise generate writes the subsystem pages" not in out
diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.py
index b449e8241..fee3b4d06 100644
--- a/tests/unit/server/mcp/conftest.py
+++ b/tests/unit/server/mcp/conftest.py
@@ -587,6 +587,7 @@ async def setup_mcp(factory, fts, vector_store, populated_db, tmp_path):
mcp_mod._embedder_status = None
mcp_mod._release_check = None
mcp_mod._release_announced = None
+ mcp_mod._keyless_note_announced = False
@pytest.fixture
diff --git a/tests/unit/server/mcp/test_meta_keyless_note.py b/tests/unit/server/mcp/test_meta_keyless_note.py
new file mode 100644
index 000000000..a20b8e58b
--- /dev/null
+++ b/tests/unit/server/mcp/test_meta_keyless_note.py
@@ -0,0 +1,65 @@
+"""``get_answer``'s ``no-llm-provider`` degraded path names what a key or a
+local model would add, once per process, never on every call (#3105).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.server.mcp_server import _meta, _state
+from repowise.server.mcp_server.tool_answer.answer import _degraded_payload
+
+HITS = [{"target_path": "pkg/mod.py", "title": "mod", "summary": "s", "score": 1.0}]
+
+
[email protected](autouse=True)
+def _clean_keyless_state(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(_state, "_keyless_note_announced", False)
+
+
+async def _payload(reason: str) -> dict:
+ return await _degraded_payload(
+ reason=reason,
+ note="DEGRADED",
+ question="how does mod work",
+ hits=HITS,
+ fallback_targets=["pkg/mod.py"],
+ repository=None,
+ t0=0.0,
+ )
+
+
+def test_first_no_llm_provider_response_carries_the_note() -> None:
+ first = _meta.keyless_note_meta()
+ assert "repowise generate" in first["keyless_note"]
+ assert "--provider ollama" in first["keyless_note"]
+
+
+def test_second_response_in_the_same_process_says_nothing() -> None:
+ _meta.keyless_note_meta()
+ assert _meta.keyless_note_meta() == {}
+
+
+async def test_degraded_payload_carries_the_note_for_no_llm_provider() -> None:
+ payload = await _payload("no-llm-provider")
+ assert "repowise generate" in payload["_meta"]["keyless_note"]
+ assert _state._keyless_note_announced is True
+
+
+async def test_degraded_payload_announces_only_once_per_session() -> None:
+ first = await _payload("no-llm-provider")
+ second = await _payload("no-llm-provider")
+ assert "keyless_note" in first["_meta"]
+ assert "keyless_note" not in second["_meta"]
+
+
+async def test_other_degraded_reasons_never_carry_the_note() -> None:
+ payload = await _payload("synthesis-failed")
+ assert "keyless_note" not in payload["_meta"]
+
+
+async def test_another_reason_does_not_use_up_the_one_announcement() -> None:
+ await _payload("synthesis-failed")
+ assert _state._keyless_note_announced is False
+ later = await _payload("no-llm-provider")
+ assert "keyless_note" in later["_meta"]