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.

feat: provider key settings and per-page AI docs generation from the reader (#988)

Raghav Chamadiya2e84d6b79a54
diff --git a/packages/api-client/src/hosted.ts b/packages/api-client/src/hosted.ts
index a95341e5a..c51ad663f 100644
--- a/packages/api-client/src/hosted.ts
+++ b/packages/api-client/src/hosted.ts
@@ -270,6 +270,11 @@ export function mapHostedPage(raw: Record<string, unknown>, repoId: string): Pag
human_notes: null,
created_at: str("created_at"),
updated_at: str("updated_at") || str("created_at"),
+ is_deterministic:
+ typeof raw.is_deterministic === "boolean"
+ ? (raw.is_deterministic as boolean)
+ : str("provider_name") === "template",
+ doc_tier: typeof raw.doc_tier === "number" ? (raw.doc_tier as number) : null,
};
}
diff --git a/packages/api-client/src/pages.test.ts b/packages/api-client/src/pages.test.ts
index 084d3fcc6..6d410a013 100644
--- a/packages/api-client/src/pages.test.ts
+++ b/packages/api-client/src/pages.test.ts
@@ -23,7 +23,7 @@ describe("regeneratePage", () => {
});
it("includes the style param for a per-page override", async () => {
- await regeneratePage("file_page:src/main.py", "caveman");
+ await regeneratePage("file_page:src/main.py", { style: "caveman" });
expect(apiPost.mock.calls[0]![3]).toEqual({
page_id: "file_page:src/main.py",
style: "caveman",
@@ -31,7 +31,15 @@ describe("regeneratePage", () => {
});
it("omits the style param for an empty override", async () => {
- await regeneratePage("file_page:src/main.py", "");
+ await regeneratePage("file_page:src/main.py", { style: "" });
expect(apiPost.mock.calls[0]![3]).toEqual({ page_id: "file_page:src/main.py" });
});
+
+ it("includes the cascade param when given", async () => {
+ await regeneratePage("file_page:src/main.py", { cascade: "dependents" });
+ expect(apiPost.mock.calls[0]![3]).toEqual({
+ page_id: "file_page:src/main.py",
+ cascade: "dependents",
+ });
+ });
});
diff --git a/packages/api-client/src/pages.ts b/packages/api-client/src/pages.ts
index b9094fb3b..2bec236a2 100644
--- a/packages/api-client/src/pages.ts
+++ b/packages/api-client/src/pages.ts
@@ -1,5 +1,10 @@
import { apiGet, apiPatch, apiPost } from "./client";
-import type { PageResponse, PageVersionResponse } from "./types";
+import type {
+ PageResponse,
+ PageVersionResponse,
+ JobLaunchResponse,
+ GenerateCascade,
+} from "./types";
export async function listPages(
repoId: string,
@@ -55,15 +60,26 @@ export async function updatePageNotes(
}
/**
- * Force-regenerate a page by ID. Pass `style` to regenerate this page in a
- * specific wiki style (per-page override); omit it to use the repo's style.
+ * Force-regenerate a single page by ID. Launches the job immediately and
+ * returns its id + stream token (D1/D5).
+ *
+ * `cascade` controls the pages that summarize this one — `none` (default)
+ * touches only this page, `dependents` also refreshes its module/layer/overview
+ * containers, `full` refreshes repo-wide. Pass `style` for a per-page wiki-style
+ * override; omit it to use the repo's style.
*/
export async function regeneratePage(
pageId: string,
- style?: string,
-): Promise<{ job_id: string }> {
- return apiPost<{ job_id: string }>("/api/pages/lookup/regenerate", undefined, undefined, {
- page_id: pageId,
- ...(style ? { style } : {}),
- });
+ opts?: { cascade?: GenerateCascade; style?: string },
+): Promise<JobLaunchResponse> {
+ return apiPost<JobLaunchResponse>(
+ "/api/pages/lookup/regenerate",
+ undefined,
+ undefined,
+ {
+ page_id: pageId,
+ ...(opts?.cascade ? { cascade: opts.cascade } : {}),
+ ...(opts?.style ? { style: opts.style } : {}),
+ },
+ );
}
diff --git a/packages/api-client/src/providers.ts b/packages/api-client/src/providers.ts
index 2bd3a6dee..a2689f2a2 100644
--- a/packages/api-client/src/providers.ts
+++ b/packages/api-client/src/providers.ts
@@ -3,7 +3,7 @@
*/
import { apiGet, apiPatch, apiPost, apiDelete } from "./client";
-import type { ProvidersResponse } from "./types";
+import type { ProvidersResponse, ProviderValidation } from "./types";
export async function getProviders(
repoId?: string,
@@ -24,13 +24,38 @@ export async function setActiveProvider(
});
}
+/** Store a key for a provider. Passing `repoId` also mirrors it into that
+ * repo's `.repowise/.env` (D6), so a later CLI run in the repo picks it up —
+ * without it the key stays server-global and the CLI never sees it. */
export async function addProviderKey(
providerId: string,
apiKey: string,
+ repoId?: string,
+): Promise<void> {
+ await apiPost(`/api/providers/${providerId}/key`, {
+ api_key: apiKey,
+ repo_id: repoId ?? null,
+ });
+}
+
+/** Remove a provider's key. Passing `repoId` also clears it from that repo's
+ * `.repowise/.env` mirror. */
+export async function removeProviderKey(
+ providerId: string,
+ repoId?: string,
): Promise<void> {
- await apiPost(`/api/providers/${providerId}/key`, { api_key: apiKey });
+ const qs = repoId ? `?repo_id=${encodeURIComponent(repoId)}` : "";
+ await apiDelete(`/api/providers/${providerId}/key${qs}`);
}
-export async function removeProviderKey(providerId: string): Promise<void> {
- await apiDelete(`/api/providers/${providerId}/key`);
+/** Live smoke test for a single provider's configured key. Never throws for a
+ * bad key — the failure is reported in `ok` / `error`. */
+export async function validateProviderKey(
+ providerId: string,
+ repoId?: string,
+): Promise<ProviderValidation> {
+ const qs = repoId ? `?repo_id=${encodeURIComponent(repoId)}` : "";
+ return apiPost<ProviderValidation>(
+ `/api/providers/${providerId}/validate${qs}`,
+ );
}
diff --git a/packages/api-client/src/repos.ts b/packages/api-client/src/repos.ts
index 9708e900b..71dff7a32 100644
--- a/packages/api-client/src/repos.ts
+++ b/packages/api-client/src/repos.ts
@@ -6,6 +6,9 @@ import type {
JobResponse,
RepoStatsResponse,
PreflightResponse,
+ GenerateRequest,
+ GenerateEstimate,
+ JobLaunchResponse,
} from "./types";
export async function listRepos(): Promise<RepoResponse[]> {
@@ -53,6 +56,25 @@ export async function preflightIndex(
);
}
+/** Cost + page counts for a generate selection, cascade fallout included.
+ * Heavy (rehydrates the graph and re-parses), so fetch it lazily — never on
+ * every render. */
+export async function generateEstimate(
+ repoId: string,
+ body: GenerateRequest,
+): Promise<GenerateEstimate> {
+ return apiPost<GenerateEstimate>(`/api/repos/${repoId}/generate/estimate`, body);
+}
+
+/** Launch a scoped generate job (writes the selected pages with a model).
+ * Returns the job id + a short-lived stream token to watch progress. */
+export async function generatePages(
+ repoId: string,
+ body: GenerateRequest,
+): Promise<JobLaunchResponse> {
+ return apiPost<JobLaunchResponse>(`/api/repos/${repoId}/generate`, body);
+}
+
export async function deleteRepo(repoId: string): Promise<{ ok: boolean; deleted_pages: number }> {
return apiDelete<{ ok: boolean; deleted_pages: number }>(`/api/repos/${repoId}`);
}
diff --git a/packages/api-client/src/types/misc.ts b/packages/api-client/src/types/misc.ts
index 4ae4957a8..bee03a308 100644
--- a/packages/api-client/src/types/misc.ts
+++ b/packages/api-client/src/types/misc.ts
@@ -37,6 +37,54 @@ export interface ProvidersResponse {
providers: ProviderInfo[];
}
+/** Result of a live provider smoke test. `ok: false` carries the reason in
+ * `error` — the endpoint never throws for a bad key. */
+export interface ProviderValidation {
+ ok: boolean;
+ provider: string | null;
+ model: string | null;
+ error: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Scoped generation (POST /repos/{id}/generate[/estimate])
+// ---------------------------------------------------------------------------
+
+export type GenerateCascade = "none" | "dependents" | "full";
+
+/** Which pages a generate/estimate call targets. Mirrors the server's
+ * `GenerateSelectionBody`. */
+export interface GenerateSelection {
+ kind: "all" | "unwritten" | "stale" | "page_ids" | "path_prefix";
+ page_ids?: string[];
+ path_prefix?: string;
+}
+
+export interface GenerateRequest {
+ selection?: GenerateSelection;
+ cascade?: GenerateCascade;
+ style?: string;
+}
+
+/** Cost + page counts for a generate selection, cascade fallout included.
+ * `estimate` is null when no provider resolves (nothing to price). */
+export interface GenerateEstimate {
+ total_pages: number;
+ pages_by_type: Record<string, number>;
+ pages_to_mark_stale: number;
+ unknown_page_ids: string[];
+ provider: { name: string | null; model: string | null; error: string | null };
+ estimate: {
+ estimated_cost_usd: number;
+ cost_low_usd: number | null;
+ cost_high_usd: number | null;
+ estimated_input_tokens: number;
+ estimated_output_tokens: number;
+ is_calibrated: boolean;
+ } | null;
+ note?: string | null;
+}
+
// ---------------------------------------------------------------------------
// API error
// ---------------------------------------------------------------------------
diff --git a/packages/api-client/src/types/pages.ts b/packages/api-client/src/types/pages.ts
index 12e3b2fe0..ac40cf677 100644
--- a/packages/api-client/src/types/pages.ts
+++ b/packages/api-client/src/types/pages.ts
@@ -23,6 +23,13 @@ export interface PageResponse {
human_notes: string | null;
created_at: string;
updated_at: string;
+ /** True when the page was rendered from structure (a template) rather than
+ * written by a model — the flat marker the server projects from
+ * `provider_name === "template"`. Drives the "Write with AI" vs
+ * "Regenerate" affordance. */
+ is_deterministic: boolean;
+ /** 2 = in-budget template, 3 = coverage tail; null on model-written pages. */
+ doc_tier: number | null;
}
export interface PageVersionResponse {
@@ -72,6 +79,15 @@ export interface JobResponse {
stream_token?: string | null;
}
+/** What a launch endpoint (`/generate`, `/pages/lookup/regenerate`, `/index`)
+ * returns: the new job's id plus a short-lived token for its SSE stream. */
+export interface JobLaunchResponse {
+ job_id: string;
+ status: string;
+ /** Present while the job is live; pass as `?token=` on the stream URL. */
+ stream_token?: string | null;
+}
+
export interface JobProgressEvent {
event: "progress" | "done" | "error";
job_id: string;
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/command.py b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
index b9a7ddcc3..a2fd2febc 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/command.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/command.py
@@ -828,16 +828,28 @@ def run_update(
# with no pages (fast mode, or an index from before templates existed)
# skip this and stay a pure index.
det_pages: list = []
+ index_only_cost = 0.0
docs_mode = resolve_docs_mode(state)
if docs_mode == "deterministic":
from .deterministic import (
load_prior_page_ids,
+ partition_regenerate_by_provenance,
persist_deterministic_pages,
regenerate_deterministic_pages,
+ regenerate_model_pages,
)
if emitter is not None:
emitter.stage("generate")
+ prior_ids = load_prior_page_ids(repo_path)
+
+ # Per-page re-render mode: a page a user upgraded to model prose must
+ # not silently revert to a template. Template pages re-render for
+ # free; model-written pages stay model-written.
+ template_paths, model_paths = partition_regenerate_by_provenance(
+ repo_path, affected.regenerate
+ )
+
det_pages = regenerate_deterministic_pages(
repo_path=repo_path,
parsed_files=parsed_files,
@@ -845,25 +857,102 @@ def run_update(
graph_builder=graph_builder,
repo_structure=repo_structure,
git_meta_map=git_meta_map,
- regenerate_paths=affected.regenerate,
+ regenerate_paths=template_paths,
cfg=cfg,
concurrency=concurrency,
degraded=degraded,
dead_code_report=dead_code_report,
- prior_page_ids=load_prior_page_ids(repo_path),
+ prior_page_ids=prior_ids,
)
- if det_pages:
+
+ # Model-written pages: re-render with the model when one resolves
+ # (D6 wrote the key into .repowise/.env, so an index-only repo whose
+ # pages were upgraded now has a provider). With no provider, keep the
+ # existing LLM content and mark it stale — never revert to a template.
+ model_pages: list = []
+ stale_model_paths: list[str] = []
+ if model_paths:
+ model_provider = None
+ try:
+ from repowise.cli.helpers import resolve_provider
+
+ model_provider = resolve_provider(
+ provider_name, model, repo_path=repo_path
+ )
+ except Exception:
+ model_provider = None
+
+ if model_provider is not None:
+ from repowise.cli.providers import build_cost_tracker
+
+ tracker = build_cost_tracker(
+ repo_path, repo_path.name, no_cost_tracking=no_cost_tracking
+ )
+ model_provider._cost_tracker = tracker
+ model_pages = regenerate_model_pages(
+ repo_path=repo_path,
+ parsed_files=parsed_files,
+ source_map=source_map,
+ graph_builder=graph_builder,
+ repo_structure=repo_structure,
+ git_meta_map=git_meta_map,
+ regenerate_paths=model_paths,
+ cfg=cfg,
+ concurrency=concurrency,
+ degraded=degraded,
+ provider=model_provider,
+ dead_code_report=dead_code_report,
+ prior_page_ids=prior_ids,
+ )
+ index_only_cost = float(getattr(tracker, "session_cost", 0.0) or 0.0)
+ # Any requested model page the render did not actually
+ # produce is kept and marked stale. generate_all catches a
+ # per-page provider error and filters that page out of its
+ # result, so a partial batch (page A rendered, page B errored)
+ # must not leave B silently fresh-but-outdated — that is the
+ # exact revert-in-disguise Task 3 prevents. Full failure
+ # (empty result) falls out of the same computation.
+ rendered_paths = {
+ pg.page_id.split("file_page:", 1)[1]
+ for pg in model_pages
+ if getattr(pg, "page_id", "").startswith("file_page:")
+ }
+ stale_model_paths = [p for p in model_paths if p not in rendered_paths]
+ else:
+ stale_model_paths = list(model_paths)
+ console.print(
+ " [yellow]![/yellow] "
+ f"{len(model_paths)} model-written page(s) changed but no "
+ "provider is configured; keeping them and marking stale. "
+ "Add a key, then run [bold]repowise generate[/bold]."
+ )
+
+ all_pages = det_pages + model_pages
+ if all_pages or stale_model_paths:
state["total_pages"] = persist_deterministic_pages(
repo_path=repo_path,
- generated_pages=det_pages,
- decay_paths=affected.decay_only,
+ generated_pages=all_pages,
+ # decay_only are cascade-reached templates; the kept model
+ # pages are stale until a provider re-writes them.
+ decay_paths=[*affected.decay_only, *stale_model_paths],
degraded=degraded,
)
- state["last_docs_commit"] = head
- console.print(
- f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "
- "wiki pages from structure"
- )
+ # Advance the docs commit only when something was actually
+ # re-rendered to HEAD; a run that only kept-and-staled model pages
+ # has not brought the wiki up to HEAD.
+ if all_pages:
+ state["last_docs_commit"] = head
+ if det_pages:
+ console.print(
+ f" [green]✓[/green] Re-rendered [bold]{len(det_pages)}[/bold] "
+ "wiki pages from structure"
+ )
+ if model_pages:
+ console.print(
+ f" [green]✓[/green] Re-wrote [bold]{len(model_pages)}[/bold] "
+ "upgraded page(s) with the model"
+ )
+ det_pages = all_pages
if emitter is not None:
emitter.stage("persist")
try:
@@ -902,7 +991,7 @@ def run_update(
emitter.done(
ok=True,
pages_generated=len(det_pages),
- cost_usd=0.0,
+ cost_usd=index_only_cost,
duration_s=time.monotonic() - start,
degraded=degraded,
)
diff --git a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
index d0e1f9cbf..2f8b8c8de 100644
--- a/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
+++ b/packages/cli/src/repowise/cli/commands/update_cmd/deterministic.py
@@ -74,6 +74,56 @@ async def _load_prior_page_ids(repo_path: Path) -> dict:
await engine.dispose()
+def partition_regenerate_by_provenance(
+ repo_path: Path, regenerate_paths: list[str]
+) -> tuple[list[str], list[str]]:
+ """Split changed file paths into (template, model_written) by existing page.
+
+ A page a user upgraded to model prose must not silently revert to a template
+ on the next update. The re-render mode is therefore per-page, read from the
+ existing ``file_page:<path>`` provenance: ``provider_name == "template"`` (or
+ no page yet) stays a template; anything else was model-written and is kept so.
+ Order within each bucket follows ``regenerate_paths``. Never raises — on a
+ lookup failure every path is treated as model-written, so the free template
+ render can never overwrite (revert) a page whose provenance we could not read.
+ A provider then re-renders them; without one the caller keeps and marks them
+ stale. Erring toward "keep" is the safe direction for the Task 3 guarantee.
+ """
+ if not regenerate_paths:
+ return [], []
+ try:
+ model_paths = run_async(_load_model_written_paths(repo_path, regenerate_paths))
+ except Exception:
+ return [], list(regenerate_paths)
+ template = [p for p in regenerate_paths if p not in model_paths]
+ model = [p for p in regenerate_paths if p in model_paths]
+ return template, model
+
+
+async def _load_model_written_paths(repo_path: Path, paths: list[str]) -> set[str]:
+ from repowise.cli.helpers import get_db_url_for_repo
+ from repowise.core.persistence import create_engine, create_session_factory, get_session
+
+ engine = create_engine(get_db_url_for_repo(repo_path))
+ try:
+ from sqlalchemy import select as sa_select
+
+ from repowise.core.persistence.models import Page
+
+ wanted = {f"file_page:{p}": p for p in paths}
+ async with get_session(create_session_factory(engine)) as session:
+ rows = await session.execute(
+ sa_select(Page.id, Page.provider_name).where(Page.id.in_(list(wanted)))
+ )
+ return {
+ wanted[pid]
+ for pid, provider_name in rows
+ if provider_name and provider_name != "template"
+ }
+ finally:
+ await engine.dispose()
+
+
def regenerate_deterministic_pages(
*,
repo_path: Path,
@@ -100,6 +150,90 @@ def regenerate_deterministic_pages(
an index-only update is the half the post-commit hook depends on, and it
has already been computed by the time this runs.
"""
+ return _render_pages(
+ repo_path=repo_path,
+ parsed_files=parsed_files,
+ source_map=source_map,
+ graph_builder=graph_builder,
+ repo_structure=repo_structure,
+ git_meta_map=git_meta_map,
+ regenerate_paths=regenerate_paths,
+ cfg=cfg,
+ concurrency=concurrency,
+ degraded=degraded,
+ dead_code_report=dead_code_report,
+ prior_page_ids=prior_page_ids,
+ provider=None,
+ degrade_label="Template page refresh",
+ )
+
+
+def regenerate_model_pages(
+ *,
+ repo_path: Path,
+ parsed_files: list,
+ source_map: dict,
+ graph_builder: Any,
+ repo_structure: Any,
+ git_meta_map: dict,
+ regenerate_paths: list[str],
+ cfg: dict,
+ concurrency: int,
+ degraded: list[str],
+ provider: Any,
+ dead_code_report: Any = None,
+ prior_page_ids: dict | None = None,
+) -> list:
+ """Re-render *regenerate_paths* with a real model, keeping them model-written.
+
+ The sibling of :func:`regenerate_deterministic_pages` for the pages a user
+ upgraded away from templates on an otherwise index-only repo. Scoped by
+ ``only_page_ids`` so the budget can't ration them down: exactly the requested
+ file pages render, from the same complete view. Never raises — a model
+ failure degrades the run, and the caller keeps the existing content and marks
+ those pages stale rather than reverting them.
+ """
+ return _render_pages(
+ repo_path=repo_path,
+ parsed_files=parsed_files,
+ source_map=source_map,
+ graph_builder=graph_builder,
+ repo_structure=repo_structure,
+ git_meta_map=git_meta_map,
+ regenerate_paths=regenerate_paths,
+ cfg=cfg,
+ concurrency=concurrency,
+ degraded=degraded,
+ dead_code_report=dead_code_report,
+ prior_page_ids=prior_page_ids,
+ provider=provider,
+ degrade_label="Model page refresh",
+ )
+
+
+def _render_pages(
+ *,
+ repo_path: Path,
+ parsed_files: list,
+ source_map: dict,
+ graph_builder: Any,
+ repo_structure: Any,
+ git_meta_map: dict,
+ regenerate_paths: list[str],
+ cfg: dict,
+ concurrency: int,
+ degraded: list[str],
+ dead_code_report: Any,
+ prior_page_ids: dict | None,
+ provider: Any,
+ degrade_label: str,
+) -> list:
+ """Shared render body for the template and model paths.
+
+ ``provider=None`` renders from templates (free, no LLM); a provider renders
+ the file pages with the model, scoped to exactly ``regenerate_paths`` via
+ ``only_page_ids`` so the coverage budget cannot drop any of them.
+ """
from repowise.core.generation import ContextAssembler, GenerationConfig, PageGenerator
from repowise.core.providers.llm.template import TemplateProvider
@@ -109,9 +243,10 @@ def regenerate_deterministic_pages(
if not affected_parsed:
return []
+ is_template = provider is None
try:
config = GenerationConfig(
- deterministic=True,
+ deterministic=is_template,
file_pages_only=True,
max_concurrency=concurrency,
language=cfg.get("language", "en"),
@@ -137,7 +272,7 @@ def regenerate_deterministic_pages(
degraded.append(f"Page embedding: {exc}")
generator = PageGenerator(
- TemplateProvider(),
+ provider if provider is not None else TemplateProvider(),
ContextAssembler(config),
config,
vector_store=vector_store,
@@ -149,7 +284,16 @@ def regenerate_deterministic_pages(
prior_pages=prior_page_ids or {},
repo_path=repo_path,
)
- with console.status(" Re-rendering wiki pages from structure…"):
+ # A model render targets exactly the requested file pages so the coverage
+ # budget can't ration them; a template render takes every page it is fed
+ # (deterministic mode bypasses the budget already).
+ only_page_ids = None if is_template else {f"file_page:{p}" for p in regenerate_paths}
+ status_msg = (
+ " Re-rendering wiki pages from structure…"
+ if is_template
+ else " Re-writing upgraded pages with the model…"
+ )
+ with console.status(status_msg):
return run_async(
generator.generate_all(
affected_parsed,
@@ -160,10 +304,11 @@ def regenerate_deterministic_pages(
git_meta_map=git_meta_map,
repo_path=repo_path,
dead_code_report=dead_code_report,
+ only_page_ids=only_page_ids,
)
)
except Exception as exc:
- degraded.append(f"Template page refresh: {exc}")
+ degraded.append(f"{degrade_label}: {exc}")
return []
diff --git a/packages/server/src/repowise/server/routers/providers.py b/packages/server/src/repowise/server/routers/providers.py
index af97bf09a..f2eeef0b8 100644
--- a/packages/server/src/repowise/server/routers/providers.py
+++ b/packages/server/src/repowise/server/routers/providers.py
@@ -98,3 +98,42 @@ async def remove_provider_key(
set_api_key(provider_id, None, repo_path=repo_path)
except ValueError as exc:
raise HTTPException(400, str(exc)) from exc
+
+
[email protected]("/{provider_id}/validate")
+async def validate_provider(
+ provider_id: str,
+ request: Request,
+ repo_id: str | None = None,
+):
+ """Live smoke test for a single provider's configured key.
+
+ Instantiates *this* provider (not the active one) with the key resolved for
+ the repo and does a tiny ``generate`` round-trip — the same probe the CLI
+ and pre-index preflight use, scoped to one provider so the settings UI can
+ confirm a key it just added actually works. A keyless provider (Ollama,
+ mock) still exercises reachability. Returns ``{ok, provider, model, error}``
+ rather than raising, so the UI renders a clean error state.
+ """
+ repo_path = await _repo_path_for(request, repo_id)
+
+ provider_name: str | None = None
+ model_name: str | None = None
+ llm_client = None
+ try:
+ from repowise.server.provider_config import get_chat_provider_instance
+
+ llm_client = get_chat_provider_instance(
+ repo_path=repo_path, repo_id=repo_id, provider_override=provider_id
+ )
+ provider_name = getattr(llm_client, "provider_name", None)
+ model_name = getattr(llm_client, "model_name", None)
+ except Exception as exc:
+ return {"ok": False, "provider": provider_id, "model": None, "error": str(exc)}
+
+ try:
+ await llm_client.generate("You are a test.", "Reply with OK.", max_tokens=50)
+ except Exception as exc:
+ return {"ok": False, "provider": provider_name, "model": model_name, "error": str(exc)}
+
+ return {"ok": True, "provider": provider_name, "model": model_name, "error": None}
diff --git a/packages/ui/src/docs/docs-reader.tsx b/packages/ui/src/docs/docs-reader.tsx
index 95ce6b194..2d3ef374c 100644
--- a/packages/ui/src/docs/docs-reader.tsx
+++ b/packages/ui/src/docs/docs-reader.tsx
@@ -10,6 +10,8 @@ import {
Loader2,
Layers,
FileInput,
+ Sparkles,
+ Cog,
} from "lucide-react";
import type { DocPage } from "@repowise-dev/types/docs";
import { cn } from "../lib/cn";
@@ -19,6 +21,8 @@ import {
isDeterministicPage,
DETERMINISTIC_BADGE_LABEL,
DETERMINISTIC_BADGE_TITLE,
+ AI_WRITTEN_BADGE_LABEL,
+ AI_WRITTEN_BADGE_TITLE,
} from "../lib/page-types";
import { computeDocNav } from "./doc-nav";
import { filterMarkdownByPersona, type ReaderPersona } from "./reader-persona";
@@ -321,13 +325,22 @@ function DocsReaderBody({
<span className="rounded-full bg-[var(--color-bg-elevated)] px-2 py-0.5 uppercase tracking-wider">
{getPageTypeLabel(page.page_type)}
</span>
- {isDeterministicPage(page) && (
+ {isDeterministicPage(page) ? (
<span
- className="rounded-full border border-[var(--color-border-default)] px-2 py-0.5 uppercase tracking-wider text-[var(--color-text-tertiary)]"
+ className="inline-flex items-center gap-1 rounded-full border border-[var(--color-info)]/35 bg-[var(--color-info)]/10 px-2 py-0.5 uppercase tracking-wider text-[var(--color-info)]"
title={DETERMINISTIC_BADGE_TITLE}
>
+ <Cog className="h-2.5 w-2.5" />
{DETERMINISTIC_BADGE_LABEL}
</span>
+ ) : (
+ <span
+ className="inline-flex items-center gap-1 rounded-full border border-[var(--color-accent-primary)]/40 bg-[var(--color-accent-muted)] px-2 py-0.5 uppercase tracking-wider text-[var(--color-accent-primary)]"
+ title={AI_WRITTEN_BADGE_TITLE}
+ >
+ <Sparkles className="h-2.5 w-2.5" />
+ {AI_WRITTEN_BADGE_LABEL}
+ </span>
)}
{moduleSeg && (
<button
diff --git a/packages/ui/src/lib/page-types.ts b/packages/ui/src/lib/page-types.ts
index 0a9d22c3e..99397eae4 100644
--- a/packages/ui/src/lib/page-types.ts
+++ b/packages/ui/src/lib/page-types.ts
@@ -74,6 +74,10 @@ export const DETERMINISTIC_BADGE_LABEL = "Auto";
export const DETERMINISTIC_BADGE_TITLE =
"Auto-documented from code structure (no AI). Factual but terse.";
+export const AI_WRITTEN_BADGE_LABEL = "AI";
+export const AI_WRITTEN_BADGE_TITLE =
+ "Written by AI from the code and its context.";
+
// ---------------------------------------------------------------------------
// Onboarding collection
// ---------------------------------------------------------------------------
diff --git a/packages/ui/src/settings/index.ts b/packages/ui/src/settings/index.ts
index b037ccb06..649cfa9f1 100644
--- a/packages/ui/src/settings/index.ts
+++ b/packages/ui/src/settings/index.ts
@@ -1 +1,2 @@
export * from "./general-form";
+export * from "./provider-settings";
diff --git a/packages/ui/src/settings/provider-settings.tsx b/packages/ui/src/settings/provider-settings.tsx
new file mode 100644
index 000000000..9f7fb658a
--- /dev/null
+++ b/packages/ui/src/settings/provider-settings.tsx
@@ -0,0 +1,346 @@
+"use client";
+
+import { useState } from "react";
+import {
+ Check,
+ KeyRound,
+ Loader2,
+ Plug,
+ Trash2,
+ X,
+} from "lucide-react";
+import { Badge } from "../ui/badge";
+import { Button } from "../ui/button";
+import { Input } from "../ui/input";
+import { Label } from "../ui/label";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "../ui/select";
+import { cn } from "../lib/cn";
+
+/** One provider row for the settings surface. Structurally a subset of the
+ * api-client `ProviderInfo`, redeclared here so the shared component stays
+ * free of any api-client dependency. */
+export interface ProviderOption {
+ id: string;
+ name: string;
+ models: string[];
+ default_model: string;
+ /** Whether a usable key is on file (server-computed; never the key itself). */
+ configured: boolean;
+}
+
+export type ProviderValidationStatus = "idle" | "testing" | "ok" | "error";
+
+export interface ProviderValidationState {
+ status: ProviderValidationStatus;
+ error?: string | null;
+}
+
+/** Providers that authenticate without an API key (local runtimes / CLIs).
+ * For these the key affordance is hidden — only reachability is validated. */
+const KEYLESS_PROVIDERS = new Set(["ollama", "opencode", "codex_cli", "mock"]);
+
+export interface ProviderSettingsProps {
+ providers: ProviderOption[];
+ /** The active provider/model selection for this repo. */
+ active: { provider: string | null; model: string | null };
+ onAddKey: (providerId: string, apiKey: string) => Promise<void> | void;
+ onRemoveKey: (providerId: string) => Promise<void> | void;
+ onSetActive: (providerId: string, model?: string) => Promise<void> | void;
+ onValidate: (providerId: string) => Promise<void> | void;
+ /** Per-provider probe state, keyed by provider id. */
+ validation?: Record<string, ProviderValidationState>;
+ /** Rendered when there are no providers at all (e.g. a fetch miss). */
+ emptyHint?: string;
+}
+
+export function ProviderSettings({
+ providers,
+ active,
+ onAddKey,
+ onRemoveKey,
+ onSetActive,
+ onValidate,
+ validation = {},
+ emptyHint = "No providers available.",
+}: ProviderSettingsProps) {
+ if (providers.length === 0) {
+ return (
+ <p className="text-sm text-[var(--color-text-tertiary)]">{emptyHint}</p>
+ );
+ }
+
+ return (
+ <div className="space-y-2.5">
+ {providers.map((provider) => (
+ <ProviderRow
+ key={provider.id}
+ provider={provider}
+ isActive={active.provider === provider.id}
+ activeModel={active.provider === provider.id ? active.model : null}
+ onAddKey={onAddKey}
+ onRemoveKey={onRemoveKey}
+ onSetActive={onSetActive}
+ onValidate={onValidate}
+ validation={validation[provider.id]}
+ />
+ ))}
+ </div>
+ );
+}
+
+function ProviderRow({
+ provider,
+ isActive,
+ activeModel,
+ onAddKey,
+ onRemoveKey,
+ onSetActive,
+ onValidate,
+ validation,
+}: {
+ provider: ProviderOption;
+ isActive: boolean;
+ activeModel: string | null;
+ onAddKey: ProviderSettingsProps["onAddKey"];
+ onRemoveKey: ProviderSettingsProps["onRemoveKey"];
+ onSetActive: ProviderSettingsProps["onSetActive"];
+ onValidate: ProviderSettingsProps["onValidate"];
+ validation: ProviderValidationState | undefined;
+}) {
+ const [editing, setEditing] = useState(false);
+ const [keyDraft, setKeyDraft] = useState("");
+ const [busy, setBusy] = useState<null | "save" | "remove" | "activate">(null);
+
+ const keyless = KEYLESS_PROVIDERS.has(provider.id);
+ const status = validation?.status ?? "idle";
+
+ async function saveKey() {
+ const key = keyDraft.trim();
+ if (!key) return;
+ setBusy("save");
+ try {
+ await onAddKey(provider.id, key);
+ setKeyDraft("");
+ setEditing(false);
+ } finally {
+ setBusy(null);
+ }
+ }
+
+ async function removeKey() {
+ setBusy("remove");
+ try {
+ await onRemoveKey(provider.id);
+ } finally {
+ setBusy(null);
+ }
+ }
+
+ async function activate(model?: string) {
+ setBusy("activate");
+ try {
+ await onSetActive(provider.id, model);
+ } finally {
+ setBusy(null);
+ }
+ }
+
+ return (
+ <div
+ className={cn(
+ "rounded-md border p-3 transition-colors",
+ isActive
+ ? "border-[var(--color-border-active)] bg-[var(--color-accent-muted)]"
+ : "border-[var(--color-border-default)]",
+ )}
+ >
+ <div className="flex items-center gap-3">
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2">
+ <span className="text-sm font-medium text-[var(--color-text-primary)]">
+ {provider.name}
+ </span>
+ {isActive && (
+ <Badge variant="accent" className="text-[10px]">
+ Active
+ </Badge>
+ )}
+ {keyless ? (
+ <Badge variant="outline" className="text-[10px]">
+ No key required
+ </Badge>
+ ) : provider.configured ? (
+ <span className="inline-flex items-center gap-1 text-[11px] text-[var(--color-success)]">
+ <Check className="h-3 w-3" />
+ Key set
+ </span>
+ ) : (
+ <span className="text-[11px] text-[var(--color-text-tertiary)]">
+ No key
+ </span>
+ )}
+ </div>
+ </div>
+
+ <div className="flex shrink-0 items-center gap-1.5">
+ {!isActive && (
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ className="h-7 text-xs"
+ disabled={busy !== null || (!keyless && !provider.configured)}
+ onClick={() => activate()}
+ aria-label={`Use ${provider.name}`}
+ >
+ {busy === "activate" ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ "Use"
+ )}
+ </Button>
+ )}
+ {(keyless || provider.configured) && (
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="h-7 gap-1.5 text-xs"
+ disabled={status === "testing"}
+ onClick={() => onValidate(provider.id)}
+ aria-label={`Test ${provider.name} connection`}
+ >
+ {status === "testing" ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ <Plug className="h-3.5 w-3.5" />
+ )}
+ Test
+ </Button>
+ )}
+ {!keyless &&
+ (editing ? null : (
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="h-7 gap-1.5 text-xs"
+ onClick={() => setEditing(true)}
+ >
+ <KeyRound className="h-3.5 w-3.5" />
+ {provider.configured ? "Update key" : "Add key"}
+ </Button>
+ ))}
+ {!keyless && provider.configured && !editing && (
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="h-7 w-7 p-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-error)]"
+ disabled={busy !== null}
+ onClick={removeKey}
+ aria-label={`Remove ${provider.name} key`}
+ >
+ {busy === "remove" ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ <Trash2 className="h-3.5 w-3.5" />
+ )}
+ </Button>
+ )}
+ </div>
+ </div>
+
+ {editing && !keyless && (
+ <div className="mt-3 flex items-center gap-2">
+ <Input
+ type="password"
+ autoComplete="off"
+ autoFocus
+ aria-label={`${provider.name} API key`}
+ value={keyDraft}
+ onChange={(e) => setKeyDraft(e.target.value)}
+ onKeyDown={(e) => {
+ if (e.key === "Enter") {
+ e.preventDefault();
+ void saveKey();
+ }
+ if (e.key === "Escape") {
+ setEditing(false);
+ setKeyDraft("");
+ }
+ }}
+ placeholder={`Paste your ${provider.name} API key`}
+ className="h-8 font-mono text-xs"
+ />
+ <Button
+ type="button"
+ size="sm"
+ className="h-8 text-xs"
+ disabled={!keyDraft.trim() || busy === "save"}
+ onClick={saveKey}
+ aria-label={`Save ${provider.name} API key`}
+ >
+ {busy === "save" ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ "Save"
+ )}
+ </Button>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ className="h-8 w-8 p-0"
+ onClick={() => {
+ setEditing(false);
+ setKeyDraft("");
+ }}
+ aria-label="Cancel"
+ >
+ <X className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+ )}
+
+ {isActive && provider.models.length > 0 && (
+ <div className="mt-3 flex items-center gap-2">
+ <Label className="text-xs text-[var(--color-text-secondary)]">Model</Label>
+ <Select
+ value={activeModel ?? provider.default_model}
+ onValueChange={(m) => activate(m)}
+ >
+ <SelectTrigger className="h-8 w-64 text-xs">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {provider.models.map((m) => (
+ <SelectItem key={m} value={m} className="text-xs">
+ {m}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </div>
+ )}
+
+ {status === "ok" && (
+ <p className="mt-2 inline-flex items-center gap-1 text-xs text-[var(--color-success)]">
+ <Check className="h-3.5 w-3.5" />
+ Connection verified
+ </p>
+ )}
+ {status === "error" && (
+ <p className="mt-2 text-xs text-[var(--color-error)]">
+ {validation?.error || "Connection failed"}
+ </p>
+ )}
+ </div>
+ );
+}
diff --git a/packages/ui/src/wiki/regenerate-button.tsx b/packages/ui/src/wiki/regenerate-button.tsx
index 9e19c886a..f73818cf4 100644
--- a/packages/ui/src/wiki/regenerate-button.tsx
+++ b/packages/ui/src/wiki/regenerate-button.tsx
@@ -1,7 +1,7 @@
"use client";
import type { ReactNode } from "react";
-import { RefreshCw } from "lucide-react";
+import { Loader2, RefreshCw, Sparkles } from "lucide-react";
import { Button } from "../ui/button";
import {
Dialog,
@@ -9,43 +9,68 @@ import {
DialogHeader,
DialogTitle,
} from "../ui/dialog";
+import { cn } from "../lib/cn";
+
+export type RegenerateMode = "write" | "regenerate";
+
+export type RegenerateCascade = "none" | "dependents" | "full";
export interface RegenerateButtonProps {
- /** Fired when the user clicks the regenerate button. Wrapper owns the
- * mutation + toast + cache-invalidation lifecycle. */
+ /** "write" for an unwritten (template) page — an inviting, accented
+ * "Write with AI"; "regenerate" for a model-written page — a quiet
+ * "Regenerate". Defaults to "regenerate". */
+ mode?: RegenerateMode;
+ /** Fired when the user clicks the button. Wrapper owns opening the confirm
+ * dialog, the mutation, the toast, and cache-invalidation. */
onRegenerate: () => void;
- /** When true, the button shows a spinning icon and is disabled (request
- * in-flight prior to a job id being assigned). */
+ /** When true, the button shows a spinner and is disabled (request in-flight
+ * prior to a job id being assigned). */
isLoading?: boolean;
- /** When true, the progress dialog is open. The wrapper sets this to
- * `true` once it receives a job id back from the regenerate mutation. */
+ /** When true, the progress dialog is open. The wrapper sets this to `true`
+ * once it receives a job id back from the regenerate mutation. */
isInProgress?: boolean;
- /** Called when the dialog requests to close (user dismiss or job done). */
+ /** Called when the progress dialog requests to close (dismiss or job done). */
onDialogClose?: () => void;
- /** Rendered inside the in-progress dialog — typically a job-progress
- * widget owned by the wrapper. */
+ /** Rendered inside the in-progress dialog — typically a job-progress widget
+ * owned by the wrapper. */
jobSlot?: ReactNode;
}
export function RegenerateButton({
+ mode = "regenerate",
onRegenerate,
isLoading = false,
isInProgress = false,
onDialogClose,
jobSlot,
}: RegenerateButtonProps) {
+ const isWrite = mode === "write";
+ const Icon = isLoading ? Loader2 : isWrite ? Sparkles : RefreshCw;
+
return (
<>
<Button
- variant="ghost"
+ variant={isWrite ? "outline" : "ghost"}
size="sm"
onClick={onRegenerate}
disabled={isLoading || isInProgress}
- className="h-7 gap-1.5 text-xs"
- aria-label="Regenerate this page"
+ className={cn(
+ "h-7 gap-1.5 text-xs",
+ isWrite &&
+ "border-[var(--color-accent-primary)]/40 bg-[var(--color-accent-muted)] text-[var(--color-accent-primary)] hover:bg-[var(--color-accent-muted)] hover:text-[var(--color-accent-hover)]",
+ )}
+ aria-label={isWrite ? "Write this page with AI" : "Regenerate this page"}
>
- <RefreshCw className={`h-3.5 w-3.5 ${isLoading ? "animate-spin" : ""}`} />
- <span className="hidden sm:inline">Regenerate</span>
+ <Icon
+ className={cn(
+ "h-3.5 w-3.5",
+ isLoading && "animate-spin",
+ isWrite && !isLoading && "text-[var(--color-accent-primary)]",
+ )}
+ />
+ <span className="hidden sm:inline">
+ {isWrite ? "Write with AI" : "Regenerate"}
+ </span>
</Button>
<Dialog
@@ -56,7 +81,9 @@ export function RegenerateButton({
>
<DialogContent className="sm:max-w-md">
<DialogHeader>
- <DialogTitle>Regenerating Page</DialogTitle>
+ <DialogTitle>
+ {isWrite ? "Writing page with AI" : "Regenerating page"}
+ </DialogTitle>
</DialogHeader>
{jobSlot}
</DialogContent>
@@ -64,3 +91,206 @@ export function RegenerateButton({
</>
);
}
+
+const CASCADE_OPTIONS: {
+ value: RegenerateCascade;
+ label: string;
+ hint: string;
+}[] = [
+ { value: "none", label: "Just this page", hint: "Fastest, cheapest." },
+ {
+ value: "dependents",
+ label: "This page and its summaries",
+ hint: "Also refreshes the module, layer, and overview pages that cover it.",
+ },
+ {
+ value: "full",
+ label: "This page and all repo-wide pages",
+ hint: "Refreshes every page that summarizes the codebase. Costs the most.",
+ },
+];
+
+export interface GenerateConfirmDialogProps {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ mode?: RegenerateMode;
+ /** Page title, shown in the body for context. */
+ pageTitle?: string;
+ cascade: RegenerateCascade;
+ onCascadeChange: (next: RegenerateCascade) => void;
+ /** Lazily-fetched estimate for the current cascade. `null` while unknown. */
+ estimate?: {
+ totalPages: number;
+ /** Preformatted cost string (e.g. "$0.01 – $0.02"); omit when no provider. */
+ costText?: string | null;
+ staleCount?: number;
+ } | null;
+ /** True while the estimate request is in flight. */
+ estimateLoading?: boolean;
+ /** A non-fatal estimate error (the launch is still allowed). */
+ estimateError?: string | null;
+ /** When no provider is configured, the dialog routes to settings instead of
+ * offering to launch. */
+ noProvider?: boolean;
+ settingsHref?: string;
+ onConfirm: () => void;
+ /** True once the launch request is in flight. */
+ launching?: boolean;
+}
+
+export function GenerateConfirmDialog({
+ open,
+ onOpenChange,
+ mode = "write",
+ pageTitle,
+ cascade,
+ onCascadeChange,
+ estimate,
+ estimateLoading = false,
+ estimateError,
+ noProvider = false,
+ settingsHref,
+ onConfirm,
+ launching = false,
+}: GenerateConfirmDialogProps) {
+ const isWrite = mode === "write";
+
+ return (
+ <Dialog open={open} onOpenChange={onOpenChange}>
+ <DialogContent className="sm:max-w-md">
+ <DialogHeader>
+ <DialogTitle className="flex items-center gap-2">
+ {isWrite && (
+ <Sparkles className="h-4 w-4 text-[var(--color-accent-primary)]" />
+ )}
+ {isWrite ? "Write this page with AI" : "Regenerate this page"}
+ </DialogTitle>
+ </DialogHeader>
+
+ {noProvider ? (
+ <div className="space-y-4">
+ <p className="text-sm text-[var(--color-text-secondary)]">
+ No AI provider is configured for this repository yet. Add a model key
+ to write documentation with AI.
+ </p>
+ <div className="flex justify-end gap-2">
+ <Button variant="ghost" size="sm" onClick={() => onOpenChange(false)}>
+ Cancel
+ </Button>
+ {settingsHref && (
+ <Button asChild size="sm">
+ <a href={settingsHref}>Add a provider key</a>
+ </Button>
+ )}
+ </div>
+ </div>
+ ) : (
+ <div className="space-y-4">
+ {pageTitle && (
+ <p className="text-sm text-[var(--color-text-secondary)]">
+ {isWrite ? "Write" : "Regenerate"}{" "}
+ <span className="font-medium text-[var(--color-text-primary)]">
+ {pageTitle}
+ </span>{" "}
+ with your configured model.
+ </p>
+ )}
+
+ <fieldset className="space-y-1.5">
+ <legend className="text-xs font-medium text-[var(--color-text-secondary)]">
+ What else to update
+ </legend>
+ {CASCADE_OPTIONS.map((opt) => (
+ <label
+ key={opt.value}
+ className={cn(
+ "flex cursor-pointer items-start gap-2.5 rounded-md border p-2.5 transition-colors",
+ cascade === opt.value
+ ? "border-[var(--color-border-active)] bg-[var(--color-accent-muted)]"
+ : "border-[var(--color-border-default)] hover:bg-[var(--color-bg-inset)]",
+ )}
+ >
+ <input
+ type="radio"
+ name="cascade"
+ value={opt.value}
+ checked={cascade === opt.value}
+ onChange={() => onCascadeChange(opt.value)}
+ className="mt-0.5 accent-[var(--color-accent-fill)]"
+ />
+ <span className="min-w-0">
+ <span className="block text-sm text-[var(--color-text-primary)]">
+ {opt.label}
+ </span>
+ <span className="block text-xs text-[var(--color-text-tertiary)]">
+ {opt.hint}
+ </span>
+ </span>
+ </label>
+ ))}
+ </fieldset>
+
+ <div
+ aria-live="polite"
+ className="rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-inset)] px-3 py-2 text-xs text-[var(--color-text-secondary)]"
+ >
+ {estimateLoading ? (
+ <span className="inline-flex items-center gap-1.5">
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ Analyzing the repository to price this accurately…
+ </span>
+ ) : estimate ? (
+ <span>
+ <span className="font-medium text-[var(--color-text-primary)]">
+ {estimate.totalPages}
+ </span>{" "}
+ {estimate.totalPages === 1 ? "page" : "pages"} to write
+ {estimate.costText ? (
+ <>
+ {" · est. "}
+ <span className="font-medium text-[var(--color-text-primary)]">
+ {estimate.costText}
+ </span>
+ </>
+ ) : null}
+ {estimate.staleCount ? (
+ <> · {estimate.staleCount} marked stale</>
+ ) : null}
+ </span>
+ ) : estimateError ? (
+ <span className="text-[var(--color-warning)]">
+ Couldn&apos;t estimate cost. {estimateError}
+ </span>
+ ) : (
+ <span>Cost estimate unavailable.</span>
+ )}
+ </div>
+
+ <div className="flex justify-end gap-2">
+ <Button
+ variant="ghost"
+ size="sm"
+ onClick={() => onOpenChange(false)}
+ disabled={launching}
+ >
+ Cancel
+ </Button>
+ <Button size="sm" onClick={onConfirm} disabled={launching}>
+ {launching ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : isWrite ? (
+ <>
+ <Sparkles className="mr-1.5 h-3.5 w-3.5" />
+ Write with AI
+ </>
+ ) : (
+ "Regenerate"
+ )}
+ </Button>
+ </div>
+ </div>
+ )}
+ </DialogContent>
+ </Dialog>
+ );
+}
diff --git a/packages/web/src/app/repos/[id]/settings/page.tsx b/packages/web/src/app/repos/[id]/settings/page.tsx
index 69975b142..0351e5796 100644
--- a/packages/web/src/app/repos/[id]/settings/page.tsx
+++ b/packages/web/src/app/repos/[id]/settings/page.tsx
@@ -3,6 +3,7 @@ import Link from "next/link";
import { notFound } from "next/navigation";
import { Settings } from "lucide-react";
import { WebhookSection } from "@/components/settings/webhook-section";
+import { ProviderSettingsPanel } from "@/components/settings/provider-settings-panel";
import { RefactoringSettingsSection } from "@/components/repos/refactoring-settings-section";
import { getRepo } from "@/lib/api/repos";
import { getCoordinatorHealth } from "@/lib/api/health";
@@ -67,6 +68,19 @@ export default async function RepoSettingsPage({ params }: Props) {
</CardContent>
</Card>
+ <Card id="provider">
+ <CardHeader>
+ <CardTitle className="text-sm font-medium">AI provider</CardTitle>
+ <CardDescription>
+ Add a model key to write documentation with AI. Keys are stored with this
+ repository and used by generation from the UI or the CLI.
+ </CardDescription>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <ProviderSettingsPanel repoId={id} />
+ </CardContent>
+ </Card>
+
<Card>
<CardHeader>
<CardTitle className="text-sm font-medium">Refactoring code generation</CardTitle>
@@ -98,7 +112,7 @@ export default async function RepoSettingsPage({ params }: Props) {
<WebhookSection />
<p className="text-xs text-[var(--color-text-tertiary)]">
- Connection, provider and MCP configuration live in{" "}
+ Server connection and MCP configuration live in{" "}
<Link
href="/settings"
className="text-[var(--color-accent-primary)] hover:underline"
diff --git a/packages/web/src/components/docs/docs-explorer.tsx b/packages/web/src/components/docs/docs-explorer.tsx
index dfeafe122..fc5d851ea 100644
--- a/packages/web/src/components/docs/docs-explorer.tsx
+++ b/packages/web/src/components/docs/docs-explorer.tsx
@@ -27,6 +27,7 @@ import {
ExportMenu,
SidebarToggle,
} from "./docs-page-actions";
+import { PageGenerateButton } from "./page-generate-button";
import { search as searchPages } from "@/lib/api/search";
import { downloadTextFile } from "@/lib/utils/download";
import { Skeleton } from "@repowise-dev/ui/ui/skeleton";
@@ -38,7 +39,7 @@ interface DocsExplorerProps {
}
export function DocsExplorer({ repoId }: DocsExplorerProps) {
- const { pages, isLoading } = usePages(repoId);
+ const { pages, isLoading, mutate } = usePages(repoId);
const [selectedPage, setSelectedPage] = useState<PageResponse | null>(null);
const [treePanelOpen, setTreePanelOpen] = useState(() => {
if (typeof window === "undefined") return true;
@@ -91,6 +92,16 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
setSelectedPage(overview ?? pages[0]);
}, [pages, pageParam, selectedPage]);
+ // After a page is (re)generated, pull the fresh page list and re-point the
+ // viewer at the updated object so its content and provenance flip in place.
+ const handleGenerated = useCallback(async () => {
+ const fresh = await mutate();
+ setSelectedPage((prev) => {
+ if (!prev || !fresh) return prev;
+ return fresh.find((p) => p.id === prev.id) ?? prev;
+ });
+ }, [mutate]);
+
const handleSelectPage = useCallback((page: PageResponse) => {
setSelectedPage(page);
// Update URL without full navigation
@@ -210,7 +221,10 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
pages={pages}
selectedPageId={selectedPage?.id ?? null}
onSelectPage={(p) => {
- handleSelectPage(p);
+ // DocsTree yields its DocPage type; the elements are the real
+ // PageResponse objects we passed in (they carry the extra
+ // provenance fields), so this narrowing is safe.
+ handleSelectPage(p as unknown as PageResponse);
if (typeof window !== "undefined" && !window.matchMedia("(min-width: 768px)").matches) {
setTreePanelOpen(false);
}
@@ -261,6 +275,13 @@ export function DocsExplorer({ repoId }: DocsExplorerProps) {
personaHasEffect={personaHasEffect}
/>
)}
+ {selectedPage && (
+ <PageGenerateButton
+ page={selectedPage}
+ repoId={repoId}
+ onGenerated={handleGenerated}
+ />
+ )}
<button
onClick={() => setSearchOpen(true)}
className="flex items-center gap-2 rounded-md border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] px-2.5 py-1.5 text-xs text-[var(--color-text-tertiary)] transition-colors hover:text-[var(--color-text-secondary)]"
diff --git a/packages/web/src/components/docs/page-generate-button.tsx b/packages/web/src/components/docs/page-generate-button.tsx
new file mode 100644
index 000000000..d649965fc
--- /dev/null
+++ b/packages/web/src/components/docs/page-generate-button.tsx
@@ -0,0 +1,160 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import { toast } from "sonner";
+import {
+ RegenerateButton,
+ GenerateConfirmDialog,
+ type RegenerateCascade,
+} from "@repowise-dev/ui/wiki/regenerate-button";
+import { toFriendlyMessage } from "@repowise-dev/ui/lib/errors";
+import { GenerationProgressWrapper } from "@/components/jobs/generation-progress-wrapper";
+import { regeneratePage } from "@/lib/api/pages";
+import { generateEstimate } from "@/lib/api/repos";
+import type { PageResponse, GenerateEstimate } from "@/lib/api/types";
+
+/** Format the estimate's cost range into a compact string. */
+function formatCost(est: GenerateEstimate["estimate"]): string | null {
+ if (!est) return null;
+ const fmt = (n: number) => `$${n < 0.01 ? n.toFixed(4) : n.toFixed(2)}`;
+ if (est.cost_low_usd != null && est.cost_high_usd != null) {
+ return `${fmt(est.cost_low_usd)} to ${fmt(est.cost_high_usd)}`;
+ }
+ return fmt(est.estimated_cost_usd);
+}
+
+/**
+ * Reader-side "Write with AI" / "Regenerate" for a single page. Owns the
+ * lazily-fetched cost estimate, the cascade choice, the launch, and the live
+ * progress — the shared `ui` components stay presentational.
+ */
+export function PageGenerateButton({
+ page,
+ repoId,
+ onGenerated,
+}: {
+ page: PageResponse;
+ repoId: string;
+ /** Called once a run completes so the host can refresh the page list. */
+ onGenerated?: () => void;
+}) {
+ const mode = page.is_deterministic ? "write" : "regenerate";
+ const settingsHref = `/repos/${repoId}/settings#provider`;
+
+ const [confirmOpen, setConfirmOpen] = useState(false);
+ const [cascade, setCascade] = useState<RegenerateCascade>("none");
+ const [estimate, setEstimate] = useState<GenerateEstimate | null>(null);
+ const [estimateLoading, setEstimateLoading] = useState(false);
+ const [estimateError, setEstimateError] = useState<string | null>(null);
+ const [launching, setLaunching] = useState(false);
+ const [jobId, setJobId] = useState<string | null>(null);
+
+ // Cache estimates per cascade so toggling the choice back doesn't refetch the
+ // heavy /generate/estimate endpoint.
+ const cacheRef = useRef<Map<RegenerateCascade, GenerateEstimate>>(new Map());
+ // The cascade whose estimate we currently want shown. A slow response for a
+ // since-abandoned cascade must not overwrite the displayed one (latest wins).
+ const wantedCascadeRef = useRef<RegenerateCascade>("none");
+
+ const fetchEstimate = useCallback(
+ async (which: RegenerateCascade) => {
+ wantedCascadeRef.current = which;
+ const cached = cacheRef.current.get(which);
+ if (cached) {
+ setEstimate(cached);
+ setEstimateError(null);
+ return;
+ }
+ setEstimateLoading(true);
+ setEstimateError(null);
+ try {
+ const res = await generateEstimate(repoId, {
+ selection: { kind: "page_ids", page_ids: [page.id] },
+ cascade: which,
+ });
+ cacheRef.current.set(which, res);
+ if (wantedCascadeRef.current === which) setEstimate(res);
+ } catch (e) {
+ if (wantedCascadeRef.current === which) {
+ setEstimateError(toFriendlyMessage(e));
+ setEstimate(null);
+ }
+ } finally {
+ if (wantedCascadeRef.current === which) setEstimateLoading(false);
+ }
+ },
+ [repoId, page.id],
+ );
+
+ function openConfirm() {
+ cacheRef.current.clear();
+ setEstimate(null);
+ setEstimateError(null);
+ setConfirmOpen(true);
+ void fetchEstimate(cascade);
+ }
+
+ function changeCascade(next: RegenerateCascade) {
+ setCascade(next);
+ void fetchEstimate(next);
+ }
+
+ async function confirm() {
+ setLaunching(true);
+ try {
+ const res = await regeneratePage(page.id, { cascade });
+ setJobId(res.job_id);
+ setConfirmOpen(false);
+ } catch (e) {
+ toast.error("Couldn't start generation", { description: toFriendlyMessage(e) });
+ } finally {
+ setLaunching(false);
+ }
+ }
+
+ const noProvider = !!estimate && estimate.provider.name == null;
+
+ return (
+ <>
+ <RegenerateButton
+ mode={mode}
+ onRegenerate={openConfirm}
+ isLoading={launching && !jobId}
+ isInProgress={jobId != null}
+ onDialogClose={() => setJobId(null)}
+ jobSlot={
+ jobId != null ? (
+ <GenerationProgressWrapper
+ jobId={jobId}
+ onDone={() => onGenerated?.()}
+ />
+ ) : null
+ }
+ />
+
+ <GenerateConfirmDialog
+ open={confirmOpen}
+ onOpenChange={setConfirmOpen}
+ mode={mode}
+ pageTitle={page.title}
+ cascade={cascade}
+ onCascadeChange={changeCascade}
+ estimate={
+ estimate && !noProvider
+ ? {
+ totalPages: estimate.total_pages,
+ costText: formatCost(estimate.estimate),
+ staleCount: estimate.pages_to_mark_stale,
+ }
+ : null
+ }
+ estimateLoading={estimateLoading}
+ estimateError={estimateError}
+ noProvider={noProvider}
+ settingsHref={settingsHref}
+ onConfirm={confirm}
+ launching={launching}
+ />
+ </>
+ );
+}
diff --git a/packages/web/src/components/settings/provider-settings-panel.tsx b/packages/web/src/components/settings/provider-settings-panel.tsx
new file mode 100644
index 000000000..a5fb13495
--- /dev/null
+++ b/packages/web/src/components/settings/provider-settings-panel.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import { toast } from "sonner";
+import { ProviderSettings } from "@repowise-dev/ui/settings/provider-settings";
+import { Skeleton } from "@repowise-dev/ui/ui/skeleton";
+import { toFriendlyMessage } from "@repowise-dev/ui/lib/errors";
+import { useProviders } from "@/lib/hooks/use-providers";
+
+/**
+ * Web data wrapper around the shared `ProviderSettings` shell. Owns the fetch,
+ * the repo-scoped key mutations (so D6 mirrors the key into `.repowise/.env`),
+ * validation, and the toasts. The shell stays presentational and hosted-portable.
+ */
+export function ProviderSettingsPanel({ repoId }: { repoId: string }) {
+ const {
+ providers,
+ active,
+ validation,
+ isLoading,
+ saveKey,
+ removeKey,
+ activate,
+ validate,
+ } = useProviders(repoId);
+
+ if (isLoading) {
+ return (
+ <div className="space-y-2.5">
+ <Skeleton className="h-16 w-full" />
+ <Skeleton className="h-16 w-full" />
+ <Skeleton className="h-16 w-full" />
+ </div>
+ );
+ }
+
+ async function handleAddKey(providerId: string, key: string) {
+ try {
+ await saveKey(providerId, key);
+ toast.success("API key saved", {
+ description: "Written to this repo. Test it to confirm it works.",
+ });
+ } catch (e) {
+ toast.error("Couldn't save the key", { description: toFriendlyMessage(e) });
+ }
+ }
+
+ async function handleRemoveKey(providerId: string) {
+ try {
+ await removeKey(providerId);
+ toast.info("API key removed");
+ } catch (e) {
+ toast.error("Couldn't remove the key", { description: toFriendlyMessage(e) });
+ }
+ }
+
+ async function handleSetActive(providerId: string, model?: string) {
+ try {
+ await activate(providerId, model);
+ } catch (e) {
+ toast.error("Couldn't set the active provider", {
+ description: toFriendlyMessage(e),
+ });
+ }
+ }
+
+ return (
+ <ProviderSettings
+ providers={providers}
+ active={active}
+ onAddKey={handleAddKey}
+ onRemoveKey={handleRemoveKey}
+ onSetActive={handleSetActive}
+ onValidate={validate}
+ validation={validation}
+ />
+ );
+}
diff --git a/packages/web/src/lib/hooks/use-providers.ts b/packages/web/src/lib/hooks/use-providers.ts
index 133320060..23b3fe64d 100644
--- a/packages/web/src/lib/hooks/use-providers.ts
+++ b/packages/web/src/lib/hooks/use-providers.ts
@@ -1,13 +1,16 @@
"use client";
+import { useState } from "react";
import useSWR from "swr";
import {
getProviders,
setActiveProvider,
addProviderKey,
removeProviderKey,
+ validateProviderKey,
} from "@/lib/api/providers";
import type { ProvidersResponse } from "@/lib/api/types";
+import type { ProviderValidationState } from "@repowise-dev/ui/settings/provider-settings";
export function useProviders(repoId?: string) {
const { data, mutate, isLoading } = useSWR<ProvidersResponse>(
@@ -16,6 +19,10 @@ export function useProviders(repoId?: string) {
{ revalidateOnFocus: false },
);
+ const [validation, setValidation] = useState<
+ Record<string, ProviderValidationState>
+ >({});
+
const activeProvider = data?.active.provider ?? null;
const activeModel = data?.active.model ?? null;
@@ -24,23 +31,52 @@ export function useProviders(repoId?: string) {
await mutate();
}
+ // Repo-scoped so D6 mirrors the key into the repo's .repowise/.env, making a
+ // later CLI run in that repo see it. Without repoId the key stays
+ // server-global and the CLI never picks it up.
async function saveKey(providerId: string, key: string) {
- await addProviderKey(providerId, key);
+ await addProviderKey(providerId, key, repoId);
await mutate();
}
async function removeKey(providerId: string) {
- await removeProviderKey(providerId);
+ await removeProviderKey(providerId, repoId);
+ setValidation((v) => {
+ const next = { ...v };
+ delete next[providerId];
+ return next;
+ });
await mutate();
}
+ async function validate(providerId: string) {
+ setValidation((v) => ({ ...v, [providerId]: { status: "testing" } }));
+ try {
+ const res = await validateProviderKey(providerId, repoId);
+ setValidation((v) => ({
+ ...v,
+ [providerId]: res.ok
+ ? { status: "ok" }
+ : { status: "error", error: res.error },
+ }));
+ } catch (e) {
+ setValidation((v) => ({
+ ...v,
+ [providerId]: { status: "error", error: (e as Error).message },
+ }));
+ }
+ }
+
return {
providers: data?.providers ?? [],
activeProvider,
activeModel,
+ active: data?.active ?? { provider: null, model: null },
isLoading,
+ validation,
activate,
saveKey,
removeKey,
+ validate,
};
}
diff --git a/tests/unit/cli/test_update_provenance_partition.py b/tests/unit/cli/test_update_provenance_partition.py
new file mode 100644
index 000000000..344393352
--- /dev/null
+++ b/tests/unit/cli/test_update_provenance_partition.py
@@ -0,0 +1,134 @@
+"""Per-page re-render mode on an index-only update.
+
+A page a user upgraded to model prose must not silently revert to a template on
+the next `repowise update`. `partition_regenerate_by_provenance` is the split
+that keeps that promise: it reads each changed file's existing page provenance
+and routes template pages to the free template render and model-written pages to
+the model render.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+import pytest
+
+from repowise.cli.commands.update_cmd.deterministic import (
+ partition_regenerate_by_provenance,
+)
+from repowise.core.generation.models import GeneratedPage
+from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_session,
+ init_db,
+ upsert_pages_from_generated,
+ upsert_repository,
+)
+
+
+def _page(path: str, provider_name: str) -> GeneratedPage:
+ now = datetime.now(UTC).isoformat()
+ return GeneratedPage(
+ page_id=f"file_page:{path}",
+ page_type="file_page",
+ title=path,
+ content="body",
+ source_hash=f"hash-{path}",
+ model_name="template" if provider_name == "template" else "gpt-x",
+ provider_name=provider_name,
+ input_tokens=0,
+ output_tokens=0,
+ cached_tokens=0,
+ generation_level=2,
+ target_path=path,
+ created_at=now,
+ updated_at=now,
+ )
+
+
+def repo_dir(tmp_path, monkeypatch):
+ (tmp_path / ".repowise").mkdir(parents=True, exist_ok=True)
+ db = tmp_path / ".repowise" / "wiki.db"
+ monkeypatch.setenv("REPOWISE_DB_URL", f"sqlite+aiosqlite:///{db.as_posix()}")
+ return tmp_path
+
+
+def _seed(repo_dir, pages: list[GeneratedPage]) -> None:
+ # Seed synchronously (asyncio.run, no running loop): the function under test
+ # is called from sync CLI code and drives its own loop via ``run_async``, so
+ # the whole test must stay off the event loop or that call raises.
+ import asyncio
+ import os
+
+ async def _do() -> None:
+ engine = create_engine(os.environ["REPOWISE_DB_URL"])
+ try:
+ await init_db(engine)
+ sf = create_session_factory(engine)
+ async with get_session(sf) as session:
+ repo = await upsert_repository(
+ session, name=repo_dir.name, local_path=str(repo_dir)
+ )
+ await upsert_pages_from_generated(session, pages, repo.id)
+ finally:
+ await engine.dispose()
+
+ asyncio.run(_do())
+
+
+def test_splits_template_from_model(repo_dir):
+ _seed(
+ repo_dir,
+ [
+ _page("a.py", "template"),
+ _page("b.py", "openai"),
+ _page("c.py", "template"),
+ ],
+ )
+ template, model = partition_regenerate_by_provenance(
+ repo_dir, ["a.py", "b.py", "c.py"]
+ )
+ assert template == ["a.py", "c.py"]
+ assert model == ["b.py"]
+
+
+def test_unknown_path_is_a_template(repo_dir):
+ # A newly added file has no page yet — it renders as a template (the free,
+ # safe default), never as a model page we can't afford.
+ _seed(repo_dir, [_page("a.py", "openai")])
+ template, model = partition_regenerate_by_provenance(repo_dir, ["a.py", "new.py"])
+ assert template == ["new.py"]
+ assert model == ["a.py"]
+
+
+def test_preserves_input_order(repo_dir):
+ _seed(repo_dir, [_page("x.py", "openai"), _page("y.py", "template")])
+ template, model = partition_regenerate_by_provenance(repo_dir, ["y.py", "x.py"])
+ assert template == ["y.py"]
+ assert model == ["x.py"]
+
+
+def test_empty_input_is_two_empty_lists(repo_dir):
+ assert partition_regenerate_by_provenance(repo_dir, []) == ([], [])
+
+
+def test_lookup_failure_keeps_pages_never_reverts(tmp_path, monkeypatch):
+ # When provenance can't be read, every path is treated as model-written so
+ # the free template render can never overwrite (revert) a page we couldn't
+ # classify. The caller then re-renders with a provider or keeps + marks stale.
+ monkeypatch.setenv(
+ "REPOWISE_DB_URL", f"sqlite+aiosqlite:///{(tmp_path / 'missing.db').as_posix()}"
+ )
+
+ def _boom(*_a, **_k):
+ raise RuntimeError("db unavailable")
+
+ monkeypatch.setattr(
+ "repowise.cli.commands.update_cmd.deterministic._load_model_written_paths",
+ _boom,
+ )
+ template, model = partition_regenerate_by_provenance(tmp_path, ["a.py", "b.py"])
+ assert template == []
+ assert model == ["a.py", "b.py"]
diff --git a/tests/unit/server/test_provider_key_endpoint.py b/tests/unit/server/test_provider_key_endpoint.py
index c962a6376..d30bd2c37 100644
--- a/tests/unit/server/test_provider_key_endpoint.py
+++ b/tests/unit/server/test_provider_key_endpoint.py
@@ -112,6 +112,65 @@ async def test_add_key_resolves_non_primary_workspace_repo(client: AsyncClient,
await ws_engine.dispose()
+class _FakeProvider:
+ provider_name = "anthropic"
+ model_name = "claude-x"
+
+ def __init__(self, raises: bool = False):
+ self._raises = raises
+
+ async def generate(self, *_a, **_k):
+ if self._raises:
+ raise RuntimeError("401 Unauthorized")
+ return "OK"
+
+
+async def test_validate_ok_when_probe_succeeds(client: AsyncClient, monkeypatch) -> None:
+ repo = await create_test_repo(client)
+ from repowise.server import provider_config as pc
+
+ monkeypatch.setattr(pc, "get_chat_provider_instance", lambda **_k: _FakeProvider())
+
+ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body == {"ok": True, "provider": "anthropic", "model": "claude-x", "error": None}
+
+
+async def test_validate_reports_probe_failure(client: AsyncClient, monkeypatch) -> None:
+ repo = await create_test_repo(client)
+ from repowise.server import provider_config as pc
+
+ monkeypatch.setattr(
+ pc, "get_chat_provider_instance", lambda **_k: _FakeProvider(raises=True)
+ )
+
+ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["ok"] is False
+ assert "401" in body["error"]
+
+
+async def test_validate_reports_missing_key(client: AsyncClient, monkeypatch) -> None:
+ repo = await create_test_repo(client)
+ from repowise.server import provider_config as pc
+
+ def _boom(**_k):
+ raise ValueError("No active provider configured. Set an API key first.")
+
+ monkeypatch.setattr(pc, "get_chat_provider_instance", _boom)
+
+ resp = await client.post(f"/api/providers/anthropic/validate?repo_id={repo['id']}")
+ assert resp.status_code == 200
+ body = resp.json()
+ assert body["ok"] is False
+ assert "API key" in body["error"]
+
+
@pytest.mark.asyncio
async def test_get_providers_returns_no_key_material(client: AsyncClient) -> None:
repo = await create_test_repo(client)