Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(cli): an occasional repowise.dev hint at the moments it helps (#3005)
Swati Ahujad34fae85998f
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.mdindex 37ac7bc8a..ece8b2eb9 100644--- a/docs/reference/CLI_REFERENCE.md+++ b/docs/reference/CLI_REFERENCE.md@@ -2173,6 +2173,21 @@ repowise telemetry disable---+### `repowise config hints on|off`++Now and then, at a moment where it would help (a finished `init`, a slow+`update`), the CLI prints one dim line on stderr about+what repowise.dev adds, with a link. At most one per run, each at most once a+week. Never under `--format json`, in CI, when stderr is not a terminal, when+you are signed in, or from `mcp`, `serve`, `watch` and hooks.++```bash+repowise config hints off # also: REPOWISE_NO_HINTS=1 or DO_NOT_TRACK=1+repowise config hints on+```++---+### `repowise login`Sign in to your hosted repowise.dev account. This is unrelated to LLM providerdiff --git a/packages/cli/src/repowise/cli/commands/config_cmd.py b/packages/cli/src/repowise/cli/commands/config_cmd.pynew file mode 100644index 000000000..c3a4d3b23--- /dev/null+++ b/packages/cli/src/repowise/cli/commands/config_cmd.py@@ -0,0 +1,28 @@+"""``repowise config``: local CLI preferences kept in ``~/.repowise``."""++from __future__ import annotations++import click++from repowise.cli.helpers import console++[email protected](name="config")+def config_group() -> None:+ """Change local CLI preferences."""+++@config_group.command(name="hints")[email protected]("state", type=click.Choice(["on", "off"]))+def config_hints(state: str) -> None:+ """Turn the occasional repowise.dev tip on or off."""+ from repowise.cli import hints++ hints.set_enabled(state == "on")+ if state == "on":+ console.print("[green]✓[/green] repowise.dev tips are on (at most one a week each).")+ else:+ console.print("[green]✓[/green] repowise.dev tips are off.")+++config_command = config_groupdiff --git a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.pyindex a8e795d62..f45bef3f2 100644--- a/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py+++ b/packages/cli/src/repowise/cli/commands/doctor_cmd/repo_checks.py@@ -357,7 +357,12 @@ def _run_repo_checks(creds = credentials.load()if creds is None:checks.append(- _check("Hosted account", True, "Not signed in (optional: repowise login)")+ _check(+ "Hosted account",+ True,+ "Not signed in (optional: repowise login). "+ "Publish this repo free: repowise publish",+ ))elif creds.get("stale"):checks.append(diff --git a/packages/cli/src/repowise/cli/commands/init_cmd/command.py b/packages/cli/src/repowise/cli/commands/init_cmd/command.pyindex 8ea0f6820..cb23baf4e 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/command.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/command.py@@ -1431,6 +1431,9 @@ def init_command())except ProviderError as exc:+ from repowise.cli.hints import maybe_hint++ maybe_hint("provider_fail")raise reasoned_error(f"Provider validation failed: {exc}",reason="provider_validation_failed",@@ -1562,6 +1565,9 @@ def init_command(f"\n{mini(EYES_SLEEPY)} [{WARN}]Interrupted.[/] Indexed work so far has been ""saved — run [bold]repowise init --resume[/] to continue where it stopped.")+ from repowise.cli.hints import maybe_hint++ maybe_hint("interrupt")return# What the run degraded on, in a place an agent can read after thediff --git a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.pyindex fd0fbb693..fb000d57b 100644--- a/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py+++ b/packages/cli/src/repowise/cli/commands/init_cmd/reporting.py@@ -118,6 +118,16 @@ def _render_defect_accuracy(result: Any) -> None:console.print()+#: From this many files, the hosted pitch is staying fresh without a long local+#: run. Lower than the fast-mode offer on purpose: a hint costs nothing to skip.+_LARGE_REPO_FILES = 1000+++def completion_hint(run_mode: str, file_count: int) -> str:+ """Which hint a finished init earns: big repos hear about freshness."""+ return "large_repo" if run_mode == "fast" or file_count >= _LARGE_REPO_FILES else "init_success"++def show_completion(*,repo_path: Any,@@ -344,6 +354,12 @@ def show_completion(console.print(_line)console.print()+ # One quiet stderr line about repowise.dev (see hints.py for when it is+ # shown); a big repo hears about staying fresh instead.+ from repowise.cli.hints import maybe_hint++ maybe_hint(completion_hint(run_mode, result.file_count))+print_files_written(console, Path(repo_path), files_written or [])_show_generation_checks(result)diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.pyindex 1c7f380c1..5ced26ca4 100644--- a/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py+++ b/packages/cli/src/repowise/cli/commands/update_cmd/reporting.py@@ -316,6 +316,7 @@ def show_full_completion(build_completion_panel("repowise update complete", metrics, next_steps=next_steps))console.print()+ _slow_update_hint(elapsed)def show_index_only_completion(@@ -371,6 +372,7 @@ def show_index_only_completion())console.print()+ _slow_update_hint(elapsed)def show_workspace_completion(@@ -407,6 +409,18 @@ def show_workspace_completion(build_completion_panel("repowise workspace update complete", metrics, next_steps=next_steps))console.print()+ _slow_update_hint(elapsed)+++#: An update slower than this is one a hosted index would have saved.+_SLOW_UPDATE_SECONDS = 60+++def _slow_update_hint(elapsed: float) -> None:+ if elapsed > _SLOW_UPDATE_SECONDS:+ from repowise.cli.hints import maybe_hint++ maybe_hint("slow_update")# ---------------------------------------------------------------------------diff --git a/packages/cli/src/repowise/cli/hints.py b/packages/cli/src/repowise/cli/hints.pynew file mode 100644index 000000000..ee228fe56--- /dev/null+++ b/packages/cli/src/repowise/cli/hints.py@@ -0,0 +1,186 @@+"""One quiet line about repowise.dev, at the moments it would help.++Rules that keep it from being a nag:++* stderr only, one dim line plus its link, never in ``--format json`` runs;+* at most one hint per command run, and each hint at most once every 7 days;+* never from ``mcp``, ``serve``, ``watch``, hooks, or anything an agent reads;+* off in CI and tests, when stderr is not a terminal, for signed-in users,+ with ``REPOWISE_NO_HINTS=1``, ``repowise config hints off`` or ``DO_NOT_TRACK``.++Deciding never touches the network: everything is read from local files and+the environment, so a hint can never slow a command down. Every local feature+works without signing in; a hint only says what the hosted side adds.+"""++from __future__ import annotations++import contextlib+import os+from dataclasses import dataclass+from datetime import UTC, datetime, timedelta++_SHOWN_KEY = "hints_shown"+_ENABLED_KEY = "hints_enabled"+_EVERY = timedelta(days=7)++#: Commands whose output belongs to an agent, a daemon or a hook.+_QUIET_COMMANDS = frozenset({"mcp", "serve", "watch", "hook", "augment"})++#: Set once a hint is shown, so a run never shows two.+_shown_this_run = False+++@dataclass(frozen=True)+class Hint:+ text: str+ #: Where the link was shown, for the site's attribution.+ src: str+ #: The section of the repowise.dev/hosted story the link opens.+ moment: str+ #: The free next step the line ends with.+ action: str = "Publish it free: repowise publish"+++#: Publishing a public repo is free (no card, up to 2 repos); anything about+#: private repos or more repos says "free for 10 days, card required".+HINTS: dict[str, Hint] = {+ "init_success": Hint(+ "Use this repo from Claude.ai or ChatGPT, or share it with your team.",+ src="cli_init_success",+ moment="mcp",+ ),+ "provider_fail": Hint(+ "Don't want to set up a key? repowise.dev writes the docs for you.",+ src="cli_provider_fail",+ moment="keys",+ action="Start free: repowise publish",+ ),+ "interrupt": Hint(+ "Big repo? repowise.dev indexes it in the cloud and keeps it fresh on every push.",+ src="cli_interrupt",+ moment="sync",+ action="Start free: repowise publish",+ ),+ "large_repo": Hint(+ "repowise.dev keeps big repos fresh automatically on every push "+ "(Pro: free for 10 days, card required).",+ src="cli_large_repo",+ moment="sync",+ ),+ "slow_update": Hint(+ "Skip manual updates: repowise.dev re-indexes on every push.",+ src="cli_slow_update",+ moment="sync",+ ),+}+++def _env_truthy(name: str) -> bool:+ return os.environ.get(name, "").strip().lower() in {"1", "true", "yes", "on"}+++def set_enabled(enabled: bool) -> None:+ """``repowise config hints on|off``."""+ from repowise.cli.platform import store++ store.update(**{_ENABLED_KEY: bool(enabled)})+++def is_enabled() -> bool:+ """The user's switch and the environment, nothing else."""+ if _env_truthy("REPOWISE_NO_HINTS") or _env_truthy("DO_NOT_TRACK"):+ return False+ from repowise.cli.platform import store++ return store.load().get(_ENABLED_KEY) is not False+++def _quiet_command() -> bool:+ try:+ import click++ ctx = click.get_current_context(silent=True)+ except Exception:+ return False+ if ctx is None:+ return False+ root = ctx.find_root()+ names = {root.invoked_subcommand, ctx.info_name}+ return bool(names & _QUIET_COMMANDS)+++def _signed_in() -> bool:+ from repowise.cli.platform import credentials++ creds = credentials.load()+ return bool(creds) and not creds.get("stale")+++def _due(hint_id: str, now: datetime) -> bool:+ from repowise.cli.platform import store++ last = (store.load().get(_SHOWN_KEY) or {}).get(hint_id)+ if not isinstance(last, str):+ return True+ try:+ return now - datetime.fromisoformat(last) >= _EVERY+ except ValueError:+ return True+++def _mark_shown(hint_id: str, now: datetime) -> None:+ from repowise.cli.platform import store++ shown = dict(store.load().get(_SHOWN_KEY) or {})+ shown[hint_id] = now.isoformat()+ store.update(**{_SHOWN_KEY: shown})+++def should_show(hint_id: str, *, fmt: str = "text") -> bool:+ if _shown_this_run or hint_id not in HINTS or fmt == "json":+ return False+ from repowise.cli.platform.telemetry.environment import is_ci++ if is_ci() or not is_enabled() or _quiet_command():+ return False+ import sys++ if not sys.stderr.isatty():+ return False+ return not _signed_in() and _due(hint_id, datetime.now(UTC))+++def maybe_hint(hint_id: str, *, fmt: str = "text") -> bool:+ """Show the hint on stderr if every rule above allows it. Never raises.++ Returns whether it was shown.+ """+ global _shown_this_run+ try:+ if not should_show(hint_id, fmt=fmt):+ return False+ hint = HINTS[hint_id]+ from rich.markup import escape++ from repowise.cli.helpers import err_console+ from repowise.cli.platform.links import site_link++ url = site_link("hosted", hint.src, fragment=hint.moment)+ # The URL is the link's own text, so a terminal without hyperlinks+ # still shows something to copy.+ err_console.print(+ f"\n [dim]{escape(hint.text)} {escape(hint.action)}\n"+ f" See how: [link={url}]{escape(url)}[/link][/dim]",+ # No syntax colouring inside a dim line, and one link, not one per token.+ highlight=False,+ )+ _shown_this_run = True+ _mark_shown(hint_id, datetime.now(UTC))+ with contextlib.suppress(Exception):+ from repowise.cli.platform import telemetry++ telemetry.add_command_outcome(hint_shown=hint_id)+ return True+ except Exception:+ return Falsediff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.pyindex b0a520a1e..fc3bcb1a3 100644--- a/packages/cli/src/repowise/cli/main.py+++ b/packages/cli/src/repowise/cli/main.py@@ -98,6 +98,7 @@ _OSS_COMMANDS: tuple[tuple[str, str], ...] = (("wiki-styles", "restyle_cmd:wiki_styles_command"),("whats-new", "whats_new_cmd:whats_new_command"),("telemetry", "telemetry_cmd:telemetry_command"),+ ("config", "config_cmd:config_command"),("publish", "publish_cmd:publish_command"),("login", "login_cmd:login_command"),("logout", "login_cmd:logout_command"),diff --git a/tests/unit/cli/test_hints.py b/tests/unit/cli/test_hints.pynew file mode 100644index 000000000..85552dfb3--- /dev/null+++ b/tests/unit/cli/test_hints.py@@ -0,0 +1,195 @@+"""The repowise.dev hints: when they show, what they say, where they link.++What protects the user: at most one line per run on stderr, each hint at most+once a week, never for agents, daemons, CI, JSON output or signed-in users,+and every way to turn them off works.+"""++from __future__ import annotations++import io+import time+from datetime import UTC, datetime, timedelta+from pathlib import Path+from unittest import mock+from urllib.parse import parse_qs, urlparse++import click+import pytest+from click.testing import CliRunner+from rich.console import Console++from repowise.cli import hints+from repowise.cli.platform import credentials, store+from repowise.cli.platform.telemetry import environment+++def stderr(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> io.StringIO:+ """A terminal-like stderr outside CI, signed out, with a fresh store."""+ monkeypatch.setattr(credentials, "_path", lambda: tmp_path / "credentials.json")+ monkeypatch.setattr(store, "_path", lambda: tmp_path / "platform.json")+ store.update(anon_id="abc123def456")+ for var in ("REPOWISE_NO_HINTS", "DO_NOT_TRACK", "REPOWISE_TELEMETRY_DISABLED"):+ monkeypatch.delenv(var, raising=False)+ monkeypatch.setattr(environment, "is_ci", lambda: False)+ monkeypatch.setattr("sys.stderr.isatty", lambda: True, raising=False)+ buf = io.StringIO()+ import repowise.cli.helpers as helpers++ monkeypatch.setattr(helpers, "err_console", Console(file=buf, width=300, highlight=False))+ monkeypatch.setattr(hints, "_shown_this_run", False)+ return buf+++def _url(text: str) -> str:+ return next(w for w in text.split() if w.startswith("https://repowise.dev/hosted"))+++class TestShowing:+ def test_shows_the_line_its_action_and_its_link(self, stderr, monkeypatch):+ from repowise.cli.platform import telemetry++ recorded: dict = {}+ monkeypatch.setattr(telemetry, "add_command_outcome", lambda **f: recorded.update(f))++ assert hints.maybe_hint("init_success") is True++ out = stderr.getvalue()+ assert "Use this repo from Claude.ai or ChatGPT, or share it with your team." in out+ assert "Publish it free: repowise publish" in out+ url = urlparse(_url(out))+ assert url.path == "/hosted" and url.fragment == "mcp"+ assert parse_qs(url.query) == {"src": ["cli_init_success"]}+ assert recorded == {"hint_shown": "init_success"}++ def test_link_has_no_install_id_with_telemetry_off(self, stderr, monkeypatch):+ monkeypatch.setenv("REPOWISE_TELEMETRY_DISABLED", "1")+ hints.maybe_hint("slow_update")+ assert parse_qs(urlparse(_url(stderr.getvalue())).query) == {"src": ["cli_slow_update"]}++ def test_one_hint_per_run(self, stderr):+ assert hints.maybe_hint("init_success")+ assert not hints.maybe_hint("slow_update")+ assert "Skip manual updates" not in stderr.getvalue()++ def test_once_a_week_per_hint(self, stderr, monkeypatch):+ assert hints.maybe_hint("slow_update")+ monkeypatch.setattr(hints, "_shown_this_run", False)+ assert not hints.maybe_hint("slow_update")++ week_ago = (datetime.now(UTC) - timedelta(days=7, minutes=1)).isoformat()+ store.update(hints_shown={"slow_update": week_ago})+ assert hints.maybe_hint("slow_update")++ def test_another_hint_is_not_blocked_by_the_week(self, stderr, monkeypatch):+ assert hints.maybe_hint("slow_update")+ monkeypatch.setattr(hints, "_shown_this_run", False)+ assert hints.maybe_hint("init_success")+++class TestNeverShown:+ @pytest.mark.parametrize("var", ["REPOWISE_NO_HINTS", "DO_NOT_TRACK"])+ def test_env_switches(self, stderr, monkeypatch, var):+ monkeypatch.setenv(var, "1")+ assert not hints.maybe_hint("init_success")+ assert stderr.getvalue() == ""++ def test_config_switch(self, stderr):+ result = CliRunner().invoke(_cli(), ["config", "hints", "off"])+ assert result.exit_code == 0, result.output+ assert not hints.maybe_hint("init_success")+ CliRunner().invoke(_cli(), ["config", "hints", "on"])+ assert hints.maybe_hint("init_success")++ def test_ci(self, stderr, monkeypatch):+ monkeypatch.setattr(environment, "is_ci", lambda: True)+ assert not hints.maybe_hint("init_success")++ def test_not_a_terminal(self, stderr, monkeypatch):+ monkeypatch.setattr("sys.stderr.isatty", lambda: False, raising=False)+ assert not hints.maybe_hint("init_success")++ def test_json_output(self, stderr):+ assert not hints.maybe_hint("init_success", fmt="json")++ def test_signed_in(self, stderr):+ credentials.save(+ {"token_kind": "api_key", "access_token": "rw_live_x", "expires": time.time()}+ )+ assert not hints.maybe_hint("init_success")++ @pytest.mark.parametrize("command", ["mcp", "serve", "watch", "hook", "augment"])+ def test_agent_daemon_and_hook_commands(self, stderr, command):+ @click.group()+ def root() -> None:+ pass++ shown: list[bool] = []++ @root.command(name=command)+ def sub() -> None:+ # CliRunner swaps stderr for a pipe; make it a terminal again so+ # only the command name can stop the hint.+ with mock.patch("sys.stderr.isatty", return_value=True):+ shown.append(hints.maybe_hint("slow_update"))++ @root.command(name="update")+ def other() -> None:+ with mock.patch("sys.stderr.isatty", return_value=True):+ shown.append(hints.maybe_hint("slow_update"))++ CliRunner().invoke(root, [command])+ assert shown == [False]+ CliRunner().invoke(root, ["update"])+ assert shown == [False, True]++ def test_unknown_hint(self, stderr):+ assert not hints.maybe_hint("nope")+++class TestWording:+ def test_every_hint_ends_with_a_free_publish_step(self):+ for hint in hints.HINTS.values():+ assert hint.action.endswith("repowise publish")+ assert hint.action.split(":")[0] in {"Publish it free", "Start free"}++ def test_one_next_step_per_line(self):+ # publish signs the person in, so a second command would only compete.+ for hint in hints.HINTS.values():+ assert f"{hint.text} {hint.action}".count("repowise ") == 1++ def test_trial_claims_name_the_card(self):+ for hint in hints.HINTS.values():+ text = f"{hint.text} {hint.action}".lower()+ if "trial" in text or "10 days" in text or "private" in text:+ assert "free for 10 days, card required" in text++ def test_moments_exist_on_the_story_page(self):+ moments = {"sync", "mcp", "bot", "security", "link", "team", "keys"}+ assert {h.moment for h in hints.HINTS.values()} <= moments+ assert all(h.src.startswith("cli_") for h in hints.HINTS.values())+++class TestPlacement:+ def test_init_picks_the_large_repo_hint_for_big_or_fast_runs(self):+ from repowise.cli.commands.init_cmd.reporting import completion_hint++ assert completion_hint("standard", 999) == "init_success"+ assert completion_hint("standard", 1000) == "large_repo"+ assert completion_hint("fast", 10) == "large_repo"++ @pytest.mark.parametrize(("elapsed", "expected"), [(59.0, []), (61.0, ["slow_update"])])+ def test_update_hints_only_when_slow(self, monkeypatch, elapsed, expected):+ from repowise.cli.commands.update_cmd import reporting++ asked: list[str] = []+ monkeypatch.setattr(hints, "maybe_hint", lambda hint_id, **kw: asked.append(hint_id))+ reporting._slow_update_hint(elapsed)+ assert asked == expected+++def _cli():+ from repowise.cli.main import cli++ return clidiff --git a/tests/unit/cli/test_lazy_commands.py b/tests/unit/cli/test_lazy_commands.pyindex a93152262..15fe3d1cf 100644--- a/tests/unit/cli/test_lazy_commands.py+++ b/tests/unit/cli/test_lazy_commands.py@@ -33,7 +33,7 @@ from repowise.core.registry import CLIRegistry, LazyCommand#: command is meant to require editing it._EXPECTED_NAMES = frozenset({- "agents", "ask", "augment", "context", "corrections", "costs", "coverage",+ "agents", "ask", "augment", "config", "context", "corrections", "costs", "coverage","dead-code", "decision", "delete", "distill", "doc-drift", "doctor","expand","export", "generate", "generate-claude-md", "health", "hook",