${escapeHtml(label(CACHE_PANEL

` 的最后）。现在顺序是： + +``` +标题 → 一句话描述 → 事实行（registry / surface / standard / 许可 / 徽章 / 仓库链接） +→ 主操作块（[Add to mcpp.toml] [☐ dev-dependency] + 命令预览） +→ 版本矩阵 → 用法示例 → 依赖 → 其它 +``` + +同时把**版本矩阵变成选择器**：每个版本是一个 button（`data-version`），点它就把上面的命令 +指到那个版本，被选中的那枚用同一套 toggle 配色标出。原来 ``, + ` ${escapeHtml(label(CACHE_PANEL_UI.budgetUnit))}`, + ` `, + ` ${estimate}`, + ` ${button("prune", label(CACHE_PANEL_UI.prune), !sharedAvailable, sharedReason)}`, + legacyBytes > 0 + ? ` ${button("cleanLegacy", label(CACHE_PANEL_UI.cleanLegacy), false, label(CACHE_PANEL_UI.reasonLegacy))}` + : "", + ``, + ].filter((line) => line.length > 0).join("\n"); +} + +/** + * The global block. Expanded it is the composition bar, the age bar, the nested + * largest-packages list and the shared actions; collapsed it is one summary line + * (`7.20 GiB · 657 entries`). The markup carries **no `open` attribute**, which + * is what makes the first render collapsed. + */ +function renderSharedBlock(model: CachePanelModel, label: UiLabel): string { + const formatters = model.format; + const notes: string[] = []; + if (model.shared.root !== undefined) { + notes.push( + `

${escapeHtml(fill(label, CACHE_PANEL_UI.sharedRoot, [model.shared.root]))}

`, + ); + } + if (model.legacy !== undefined && model.legacy.path !== undefined) { + notes.push( + `

${escapeHtml(fill(label, CACHE_PANEL_UI.legacyPath, [model.legacy.path]))}

`, + ); + } + + const body = [ + renderComposition(model, label), + renderAge(model, label), + renderTop(model, label), + renderSharedActions(model, label), + ...notes, + ].join("\n"); + + if (!model.shared.available) { + // A failure must not be hidden behind a collapsed disclosure: render the + // block open, with the reason where the summary would have been. + return [ + `

`, + `

${escapeHtml(label(CACHE_PANEL_UI.sharedTitle))}

`, + `

${escapeHtml(model.shared.note ?? label(CACHE_PANEL_UI.sharedUnavailable))}

`, + renderSharedActions(model, label), + `

`, + ].join("\n"); + } + + const summary = `${formatters.bytes(finite(model.shared.totalBytes))} · ${fill( + label, + CACHE_PANEL_UI.sharedEntries, + [formatters.count(finite(model.shared.totalEntries))], + )}`; + return [ + `

`, + `

`, + ` ${escapeHtml(label(CACHE_PANEL_UI.sharedTitle))}`, + ` ${escapeHtml(summary)}`, + `

`, + `

`, + body, + `

`, + `

`, + ].join("\n"); +} + +// ───────────────────────────────────────────────────────────────── client + +/** + * The client. Dependency-free, no template literals of its own, and it only + * posts messages: the host re-renders the whole document after every action, so + * there is exactly one renderer instead of two. + * + * The open/closed state of the two `

` is the one thing the client + * remembers (`setState`), so re-rendering after an action does not re-collapse + * the block the user just opened. The document itself still ships collapsed. + */ +function clientScript(): string { + return `(function () { + "use strict"; + var api = typeof acquireVsCodeApi === "function" ? acquireVsCodeApi() : undefined; + var saved = {}; + if (api && typeof api.getState === "function") { + try { saved = api.getState() || {}; } catch (error) { saved = {}; } + } + + function post(message) { + if (api) { api.postMessage(message); } + } + + function detailsList() { + return document.querySelectorAll("details[data-details]"); + } + + function restoreOpen() { + var open = saved && typeof saved.open === "object" && saved.open !== null ? saved.open : {}; + var all = detailsList(); + for (var index = 0; index < all.length; index += 1) { + var id = all[index].getAttribute("data-details"); + if (id && open[id] === true) { all[index].open = true; } + } + } + + function rememberOpen() { + var open = {}; + var all = detailsList(); + for (var index = 0; index < all.length; index += 1) { + var id = all[index].getAttribute("data-details"); + if (id) { open[id] = all[index].open === true; } + } + saved.open = open; + if (api && typeof api.setState === "function") { api.setState(saved); } + } + + function budgetGiB() { + var input = document.getElementById("cache-budget"); + if (!input) { return undefined; } + var text = String(input.value).trim(); + if (text.length === 0) { return undefined; } + var value = Number(text); + if (!isFinite(value) || value < 0) { return undefined; } + return value; + } + + document.addEventListener("click", function (event) { + var target = event.target; + if (!target || typeof target.closest !== "function") { return; } + var button = target.closest("button"); + if (!button || button.disabled) { return; } + var entry = button.getAttribute("data-show-entry"); + if (entry) { post({ type: "showEntry", label: entry }); return; } + var action = button.getAttribute("data-action"); + if (!action) { return; } + if (action === "collect") { + var value = budgetGiB(); + if (value === undefined) { return; } + post({ type: "collect", budgetGiB: value }); + return; + } + post({ type: action }); + }); + + // A toggle event does not bubble, so the listener captures it on the way down. + document.addEventListener("toggle", function (event) { + var target = event.target; + if (target && typeof target.getAttribute === "function" && target.hasAttribute("data-details")) { + rememberOpen(); + } + }, true); + + restoreOpen(); +})();`; +} + +// ───────────────────────────────────────────────────────────── the document + +/** The whole document. */ +export function renderCachePanelHtml(model: CachePanelModel, assets: CachePanelAssets): string { + const label: UiLabel = (key) => model.ui[key] ?? key; + const csp = `default-src 'none'; style-src ${assets.cspSource}; script-src 'nonce-${assets.nonce}'; img-src ${assets.cspSource}`; + const body = [ + renderWarnings(model, label), + renderProjectBlock(model, label), + renderSharedBlock(model, label), + `

${escapeHtml(label(CACHE_PANEL_UI.boundary))}

`, + ] + .filter((part) => part.length > 0) + .join("\n"); + return ` + + + + + + +${escapeHtml(label(CACHE_PANEL_UI.title))} + + + +

+${body} +

+ + + +`; +} + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function nonEmptyString(value: unknown): value is string { + return typeof value === "string" && value.length > 0; +} + +/** + * Decode one `postMessage` payload. Webview input is untrusted: anything that is + * not exactly one of the eight shapes is dropped, and the returned object is + * rebuilt so foreign fields never travel further. + * + * `collect` needs a finite, non-negative `budgetGiB`; a payload without one is + * not a request this panel can honour. + */ +export function decodeCachePanelMessage(raw: unknown): CachePanelMessage | undefined { + if (!isRecord(raw)) { + return undefined; + } + switch (raw.type) { + case "refresh": + case "cleanStale": + case "cleanProject": + case "prune": + case "verify": + case "cleanLegacy": + return { type: raw.type }; + case "collect": { + const budget = raw.budgetGiB; + if (typeof budget !== "number" || !Number.isFinite(budget) || budget < 0) { + return undefined; + } + return { type: "collect", budgetGiB: budget }; + } + case "showEntry": + return nonEmptyString(raw.label) ? { type: "showEntry", label: raw.label } : undefined; + default: + return undefined; + } +} diff --git a/src/cache/cacheState.ts b/src/cache/cacheState.ts new file mode 100644 index 0000000..f90b9e9 --- /dev/null +++ b/src/cache/cacheState.ts @@ -0,0 +1,188 @@ +/** + * The cache view's decisions, as **data**. + * + * Everything here is deliberately free of `vscode` and of the file system, so the + * settings that shape the cache view can be tested directly: + * + * - whether the pre-v1 cache node is offered (`mcpp.cache.showLegacy`, §8 G6); + * - what the panel is allowed to say about that cache; + * - the warning node for `mcpp.cache.warnAboveGiB`; + * - the extra confirmation `mcpp.cache.gc.confirmAboveGiB` adds; + * - the snapshot the environment self-check reads (`showSelfCheck`, §8 G9). + * + * `src/cache/cacheView.ts` reads the settings and hands the values in; the + * `vscode` layer therefore stays thin enough to read in one sitting. + */ + +import { formatBytes } from "../util/format"; + +/** 1 GiB, binary — the unit both cache size settings are declared in. */ +export const BYTES_PER_GIB = 1024 ** 3; + +/** + * A node built here rather than in `./models.ts`, so the tree model needs no + * edit: the shape is structurally the tree's `TreeNode`. The cache view itself is + * a sidebar `WebviewView` since §8.1 and no longer builds a tree, so this node is + * kept as the policy (§8 G6) that the warning threshold is decided in one pure + * place — the view states the same threshold in + * `src/cache/cachePanelHtml.ts`'s warning banner. + */ +export interface CacheTreeNode { + id: string; + label: { key: string; args?: readonly (string | number)[] }; + description?: { key: string; args?: readonly (string | number)[] }; + tooltip?: { key: string; args?: readonly (string | number)[] }; + icon?: string; + contextValue?: string; + command?: { command: string; title: { key: string; args?: readonly (string | number)[] } }; + children?: readonly CacheTreeNode[]; +} + +/** `mcpp.cache.showLegacy`, as the view reads it. */ +export interface LegacyGate { + enabled: boolean; + bytes?: number; + files?: number; + truncated?: boolean; +} + +export type LegacyDisplay = "shown" | "off" | "empty" | "unknown"; + +/** Why the pre-v1 node is or is not in the tree. Pure, so the policy is testable. */ +export function legacyDisplay(gate: LegacyGate): LegacyDisplay { + if (!gate.enabled) { + return "off"; + } + if (gate.bytes === undefined) { + return "unknown"; + } + return gate.bytes > 0 ? "shown" : "empty"; +} + +/** + * The figure the tree needs, or `undefined` when no node should exist. Kept next + * to {@link legacyDisplay} so "the node renders only when the setting is on and + * the directory is non-empty" is stated once. + */ +export function legacyBytesForTree(gate: LegacyGate): number | undefined { + return legacyDisplay(gate) === "shown" ? gate.bytes : undefined; +} + +/** What the panel may show: the same rule, plus the path it can offer to clean. */ +export function legacyForPanel( + gate: LegacyGate, + path: string | undefined, +): { bytes: number; path?: string } | undefined { + if (legacyDisplay(gate) !== "shown" || path === undefined) { + return undefined; + } + return { bytes: gate.bytes ?? 0, path }; +} + +/** + * The warning the tree shows when the shared cache reached `mcpp.cache.warnAboveGiB`. + * + * `0` — and a non-positive or unreadable threshold — disables the warning + * entirely, which is what the registry's description promises. `bytes` must come + * from the same read the rest of the view uses; a missing inventory is not a + * warning (nothing was measured, so nothing is known to be large). + */ +export function buildCacheWarningNode(bytes: number, thresholdGiB: number): CacheTreeNode | undefined { + if (!Number.isFinite(thresholdGiB) || thresholdGiB <= 0) { + return undefined; + } + if (!Number.isFinite(bytes) || bytes < thresholdGiB * BYTES_PER_GIB) { + return undefined; + } + const thresholdBytes = thresholdGiB * BYTES_PER_GIB; + return { + id: "cache.warning", + label: { key: "Cache warning" }, + description: { key: "{0} · at or above {1}", args: [formatBytes(bytes), formatBytes(thresholdBytes)] }, + tooltip: { + key: "The shared build cache is {0}. Raise or clear mcpp.cache.warnAboveGiB to change when this appears.", + args: [formatBytes(bytes)], + }, + icon: "warning", + contextValue: "mcppCacheWarning", + // The cache view is a sidebar `WebviewView` now, so the node points at the + // view's own focus command (VS Code registers `.focus` for every + // contributed view) rather than at the removed `mcpp.showCachePanel`. + command: { command: "mcpp.cache.focus", title: { key: "Cache statistics" } }, + }; +} + +/** `mcpp.cache.gc.confirmAboveGiB`: does this budget add a confirmation level? */ +export function gcBudgetNeedsExtraConfirm(budgetGiB: number, confirmAboveGiB: number): boolean { + if (!Number.isFinite(budgetGiB) || budgetGiB < 0) { + return false; + } + if (!Number.isFinite(confirmAboveGiB) || confirmAboveGiB < 0) { + return false; + } + // 0 means "confirm every cleanup", including the one with no budget at all. + return confirmAboveGiB === 0 || budgetGiB >= confirmAboveGiB; +} + +export interface GcBudgetDialog { + /** Substituted into the caller's `detail` key: the budget in GiB. */ + args: readonly (string | number)[]; +} + +/** + * The data the extra level's dialogue needs. + * + * It deliberately carries no sentences: the caller writes the translation + * literals (as `src/cli/clean.ts` does with its `titleKey`/`detailKey`), which is + * what makes `tools/l10n-check.mjs` see them. This module only decides *when* the + * dialogue happens and what number it names. + */ +export function gcBudgetDialog(budgetGiB: number, confirmAboveGiB: number): GcBudgetDialog { + // A budget of 0 means "no budget given": the threshold is the figure worth + // naming in that case. + const named = budgetGiB > 0 ? budgetGiB : confirmAboveGiB; + return { args: named > 0 ? [named] : [] }; +} + +/** What the environment self-check puts under `Cache` (`cli/selfCheck.ts` §8 G9). */ +export interface CacheSnapshot { + totalBytes: number; + entries: number; + incomplete: number; +} + +/** + * The snapshot from an inventory the caller already read. No query is repeated + * here; `readCacheSnapshot()` in `src/cache/cacheView.ts` is the one that runs + * them, and it reuses the cache view's own read path. + */ +export function cacheSnapshotFrom( + inventory: { totalBytes: number; totalEntries: number; incomplete: number } | undefined, +): CacheSnapshot | undefined { + if (inventory === undefined) { + return undefined; + } + return { + totalBytes: Number.isFinite(inventory.totalBytes) ? inventory.totalBytes : 0, + entries: Number.isFinite(inventory.totalEntries) ? inventory.totalEntries : 0, + incomplete: Number.isFinite(inventory.incomplete) ? inventory.incomplete : 0, + }; +} + +export interface TimerDecision { + active: boolean; + seconds: number; +} + +/** + * Whether one of the two view timers should be running. + * + * Every condition that turns a timer off is stated once, in one place: + * `0` (or anything that is not a positive finite number) disables it, and so does + * a view that is not visible. The two settings differ only in what feeds + * `viewVisible`. + */ +export function refreshTimerDecision(seconds: number, viewVisible: boolean): TimerDecision { + const usable = Number.isFinite(seconds) && seconds > 0; + return { active: usable && viewVisible, seconds: usable ? seconds : 0 }; +} diff --git a/src/cache/cacheView.ts b/src/cache/cacheView.ts new file mode 100644 index 0000000..40ef2cc --- /dev/null +++ b/src/cache/cacheView.ts @@ -0,0 +1,762 @@ +/** + * The cache view and every cleanup command. + * + * The view is a sidebar **WebviewView** (`mcpp.cache`, plan §8.1): the numbers + * and the bars live in one document whose host is `src/cache/cachePanel.ts`, and + * whose structure is the pure `src/cache/cachePanelHtml.ts`. This file owns the + * data behind it, the status item, the auto-refresh timer and the commands. + * + * The *policy* — which argv, how much confirmation, whether a preview is shown — + * lives in `src/cli/clean.ts` and is unit-tested there. This file only asks the + * user, runs the command and reports the result, so the safety rules cannot be + * edited by accident in a UI change. + * + * Nothing here removes anything by itself: every destructive path goes through + * `planClean`, a preview when the plan asks for one, and a modal. + * + * Four settings shape this file: + * + * - `mcpp.cache.showLegacy` decides whether the pre-v1 cache is measured and + * offered at all (`src/cache/cacheState.ts`, §8 G6); + * - `mcpp.cache.warnAboveGiB` adds a warning when the shared cache is large; + * - `mcpp.cache.autoRefreshSeconds` re-reads while the view is on screen; + * - `mcpp.cache.gc.confirmAboveGiB` adds one confirmation level to a large `gc`. + */ + +import * as vscode from "vscode"; + +import { estimateArtifacts, measureDirectory, type ArtifactEstimate } from "../cli/artifacts"; +import { parseCacheDir, parseCacheList, summarizeCache, type CacheInventory, type CacheEntry } from "../cli/cache"; +import { planClean, withSharedCache, type CleanPlan } from "../cli/clean"; +import { runMcpp, type ProcessResult } from "../cli/process"; +import { CACHE_COMMANDS } from "../commands/ids"; +import { read } from "../config/access"; +import { format as formatMessage, t } from "../i18n/t"; +import { PollTimer } from "../mcppls/timers"; +import type { McppProjectDiscovery } from "../projects/discovery"; +import { formatBytes, projectGc } from "../util/format"; +import { clampOutput } from "../util/text"; +import { + cacheSnapshotFrom, + gcBudgetDialog, + gcBudgetNeedsExtraConfirm, + legacyForPanel, + refreshTimerDecision, + type CacheSnapshot, +} from "./cacheState"; +import { + CACHE_VIEW_ID, + CACHE_VIEW_FOCUS_COMMAND, + registerCachePanel, + type CachePanelData, + type CachePanelProvider, +} from "./cachePanel"; + +export { CACHE_VIEW_ID, CACHE_VIEW_FOCUS_COMMAND }; + +/** The tick granularity; `mcpp.cache.autoRefreshSeconds` is in seconds. */ +const REFRESH_TICK_MS = 100; + +/** The pre-v1 walk is a courtesy figure, so it gets a smaller budget than `target/`. */ +const LEGACY_MAX_ENTRIES = 20_000; + +/** `mcpp.runtime.timeoutSeconds`, or the built-in default when it is 0. */ +function queryTimeoutMs(): number | undefined { + const seconds = read("mcpp.runtime.timeoutSeconds"); + return seconds > 0 ? seconds * 1000 : 60_000; +} +const CLEAN_TIMEOUT_MS = 300_000; + +export interface CacheViewDeps { + output: vscode.OutputChannel; + currentProject: () => McppProjectDiscovery | undefined; + mcppExecutable: (project: McppProjectDiscovery | undefined) => string; + isTrusted: () => boolean; +} + +/** What `mcpp cache dir` reported about the pre-v1 cache, measured or not. */ +interface LegacyCache { + path?: string; + bytes?: number; + files?: number; + truncated?: boolean; +} + +interface CacheState { + entries: CacheEntry[]; + inventory?: CacheInventory; + artifacts?: ArtifactEstimate; + legacy?: LegacyCache; + error?: string; +} + +function workingDirectory(project: McppProjectDiscovery | undefined): string | undefined { + return project?.root; +} + +/** Unix seconds -> an ISO instant the panel can print; the panel does not do dates. */ +function timestamp(seconds: number | undefined): string | undefined { + return seconds === undefined || !Number.isFinite(seconds) ? undefined : new Date(seconds * 1000).toISOString(); +} + +function numberFormat(): "binary" | "decimal" { + return read("mcpp.ui.numberFormat") === "decimal" ? "decimal" : "binary"; +} + +/** + * `mcpp.cache.showLegacy`: the whole rule in one object, so the panel and the + * self-check read the same answer. + */ +function legacyGate(settings: { showLegacy: boolean }, legacy: LegacyCache | undefined): { + enabled: boolean; + bytes?: number; + files?: number; + truncated?: boolean; +} { + return { + enabled: settings.showLegacy, + bytes: legacy?.bytes, + files: legacy?.files, + truncated: legacy?.truncated, + }; +} + +function viewSettings(): { + topN: number; + ageBoundaries: string[]; + showLegacy: boolean; + warnAboveGiB: number; + autoRefreshSeconds: number; +} { + return { + topN: Math.max(1, read("mcpp.views.cache.topN")), + ageBoundaries: read("mcpp.views.cache.ageBuckets"), + showLegacy: read("mcpp.cache.showLegacy") !== false, + warnAboveGiB: read("mcpp.cache.warnAboveGiB"), + autoRefreshSeconds: read("mcpp.cache.autoRefreshSeconds"), + }; +} + +async function appendResult( + deps: CacheViewDeps, + title: string, + executable: string, + argv: readonly string[], + cwd: string | undefined, + result: ProcessResult, +): Promise { + try { + deps.output.appendLine(`\n[${new Date().toISOString()}] ${title}`); + deps.output.appendLine(`$ ${[executable, ...argv].join(" ")}`); + const stdout = clampOutput(result.stdout); + const stderr = clampOutput(result.stderr); + if (stdout.text.trim().length > 0) deps.output.appendLine(stdout.text.trimEnd()); + if (stderr.text.trim().length > 0) deps.output.appendLine(stderr.text.trimEnd()); + deps.output.appendLine(`[exit ${result.exitCode}]`); + } catch { + // The channel can already be gone during shutdown. + } +} + +async function run( + deps: CacheViewDeps, + project: McppProjectDiscovery | undefined, + argv: readonly string[], + options: { timeoutMs?: number; quiet?: boolean } = {}, +): Promise { + const executable = deps.mcppExecutable(project); + const cwd = workingDirectory(project); + const result = options.quiet === true + ? await runMcpp(deps.isTrusted(), executable, [...argv], cwd, { timeoutMs: options.timeoutMs, maxBufferMiB: read("mcpp.runtime.maxOutputMiB") }) + : await vscode.window.withProgress( + { location: vscode.ProgressLocation.Notification, title: `mcpp ${argv[0]}` }, + () => runMcpp(deps.isTrusted(), executable, [...argv], cwd, { timeoutMs: options.timeoutMs }), + ); + if (result === undefined) { + // The seam refuses in an untrusted workspace; the callers gate with their + // own message, so this is the defensive shape of the same refusal. + return { exitCode: 1, stdout: "", stderr: t("the workspace is not trusted") }; + } + if (result.exitCode !== 0 || options.quiet !== true) { + await appendResult(deps, `mcpp ${argv.join(" ")}`, executable, argv, cwd, result); + } + return result; +} + +async function preview(title: string, content: string): Promise { + const document = await vscode.workspace.openTextDocument({ + content: `# ${title}\n\n\`\`\`\n${content.trimEnd()}\n\`\`\`\n`, + language: "markdown", + }); + await vscode.window.showTextDocument(document, { preview: true, preserveFocus: true }); +} + +/** + * Ask for confirmation, honouring the plan's level. Level 3 asks twice: once as + * a modal and once with an explicit acknowledgement, because that is the one + * that reaches every project on the machine. + */ +async function confirmPlan(plan: CleanPlan, detail: string, figures: string): Promise { + const body = `${t(plan.detailKey, figures)}\n\n${detail}`; + if (plan.level === 0) { + return true; + } + const runLabel = t("Run"); + const choice = await vscode.window.showWarningMessage( + t(plan.titleKey), + { modal: true, detail: body }, + runLabel, + ); + if (choice !== runLabel) { + return false; + } + if (!plan.acknowledge) { + return true; + } + const acknowledge = t("I understand this affects every mcpp project on this machine"); + const second = await vscode.window.showWarningMessage( + t("Confirm once more"), + { modal: true, detail: body }, + acknowledge, + ); + return second === acknowledge; +} + +/** + * The extra level `mcpp.cache.gc.confirmAboveGiB` adds. + * + * It is asked *before* the plan's own modal, so a refused acknowledgement never + * reaches the dialogue that would have run the command. It never replaces a + * level: a plan that already demands an acknowledgement is not asked a third + * time, and the plan's own modal still runs afterwards. + * + * The sentences live here rather than in `cacheState.ts` so + * `tools/l10n-check.mjs` sees them as translation call literals; the decision and + * the figure come from the pure module. + */ +export function extraGcConfirmation( + plan: CleanPlan, + budgetGiB: number, + confirmAboveGiB: number, +): { title: string; detail: string; acknowledge: string; args: readonly (string | number)[] } | undefined { + if (plan.action !== "cacheGc" || plan.acknowledge) { + return undefined; + } + if (!gcBudgetNeedsExtraConfirm(budgetGiB, confirmAboveGiB)) { + return undefined; + } + const dialog = gcBudgetDialog(budgetGiB, confirmAboveGiB); + return { + title: t("Confirm a cleanup this large"), + detail: t( + "This {0} GiB budget frees entries that every mcpp project on this machine shares. The cleanup can take a while, and any dropped entry is rebuilt on next use.", + ), + acknowledge: t("I understand this removes entries other mcpp projects may use"), + args: dialog.args, + }; +} + +/** + * The cache view and its commands. + * + * Returns the sidebar provider it registered, so a caller that would rather own + * the `registerWebviewViewProvider` call can register this value itself instead + * (see `registerCachePanel`). Ignoring the return value is the normal case: the + * view is registered here, and `extension.ts` needs no extra line. + */ +export function registerCacheView(context: vscode.ExtensionContext, deps: CacheViewDeps): CachePanelProvider { + let state: CacheState = { entries: [] }; + /** Guards the interval: one refresh at a time, and none after a failure. */ + let refreshInFlight: Promise | undefined; + /** + * The sidebar view. Assigned after the timer below is declared, because the + * timer asks the provider whether the view is on screen; everything that reads + * it does so long after `registerCacheView` has returned. + */ + let provider: CachePanelProvider | undefined; + const viewVisible = (): boolean => provider?.visible === true; + + // An optional, second status item. Off by default: the C++ Modules extension + // already owns a status item, and the mcpp quick menu owns ours. + const status = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 39); + // `mcpp.cache.focus` is registered by VS Code for the contributed view, so the + // status item can bring the sidebar view on screen without a command of ours. + status.command = CACHE_VIEW_FOCUS_COMMAND; + context.subscriptions.push(status); + + const updateStatus = (): void => { + if (!read("mcpp.cache.statusBar")) { + status.hide(); + return; + } + const total = state.inventory?.totalBytes; + status.text = total === undefined ? "$(database) mcpp" : `$(database) ${formatBytes(total, numberFormat())}`; + status.tooltip = t("Shared build cache"); + status.show(); + }; + + const applyState = (next: CacheState): void => { + state = next; + setLastCacheSnapshot( + next.inventory === undefined + ? undefined + : cacheSnapshotFrom({ + totalBytes: next.inventory.totalBytes, + totalEntries: next.inventory.totalEntries, + incomplete: next.inventory.incomplete.length, + }), + ); + }; + + /** + * Re-read everything the view shows. It deliberately does **not** redraw the + * webview: the draw path (`CachePanelDeps.read` is `read` + `panelData`) calls + * this first, and a redraw from inside here would ask itself for the same + * figures again. + */ + const refreshNow = async (): Promise => { + const project = deps.currentProject(); + const settings = viewSettings(); + const next: CacheState = { entries: [] }; + + if (!deps.isTrusted()) { + next.error = t("the workspace is not trusted"); + applyState(next); + return; + } + + const listed = await run(deps, project, ["cache", "list", "--format", "json"], { + timeoutMs: queryTimeoutMs(), + quiet: true, + }); + if (listed.exitCode === 0) { + const parsed = parseCacheList(listed.stdout); + if (parsed === undefined) { + next.error = t("mcpp cache list did not return the documented document"); + } else { + next.entries = parsed.entries; + next.inventory = summarizeCache(parsed.root, parsed.entries, { + topN: settings.topN, + ageBoundaries: settings.ageBoundaries, + }); + } + } else { + next.error = t("mcpp cache list failed (exit {0})", listed.exitCode); + } + + const dir = await run(deps, project, ["cache", "dir"], { timeoutMs: queryTimeoutMs(), quiet: true }); + if (dir.exitCode === 0) { + const parsed = parseCacheDir(dir.stdout); + // The pre-v1 directory is measured only when the setting offers it: a + // user who turned `mcpp.cache.showLegacy` off pays for no walk at all. + const measured = + settings.showLegacy && parsed.legacyPath !== undefined + ? measureDirectory(parsed.legacyPath, { maxEntries: LEGACY_MAX_ENTRIES }) + : undefined; + next.legacy = { + path: parsed.legacyPath, + bytes: measured?.totalBytes, + files: measured?.files, + truncated: measured?.truncated !== undefined, + }; + } + + if (project !== undefined && read("mcpp.cache.estimateProjectBytes")) { + next.artifacts = estimateArtifacts(project.root); + } + + applyState(next); + updateStatus(); + }; + + /** Single-flight: an interval tick during a read must not start a second one. */ + const refresh = (): Promise => { + if (refreshInFlight !== undefined) { + return refreshInFlight; + } + refreshInFlight = refreshNow().finally(() => { + refreshInFlight = undefined; + }); + return refreshInFlight; + }; + + /** The figures a confirmation dialogue needs, without running anything new. */ + const figures = (): string => { + const total = state.inventory?.totalBytes; + return total === undefined ? t("(size unknown)") : t("{0} in the shared cache", formatBytes(total)); + }; + + const runPlan = async (project: McppProjectDiscovery | undefined, plan: CleanPlan, extra = ""): Promise => { + const detail = `${t("Command")}: mcpp ${plan.argv.join(" ")}${extra}`; + if (!(await confirmPlan(plan, detail, figures()))) { + return; + } + const result = await run(deps, project, plan.argv, { timeoutMs: CLEAN_TIMEOUT_MS }); + if (result.exitCode === 0) { + await refresh(); + return; + } + void vscode.window.showErrorMessage(t("mcpp {0} failed with exit code {1}", plan.argv.join(" "), result.exitCode)); + }; + + /** `runPlan` plus the one extra level `mcpp.cache.gc.confirmAboveGiB` adds. */ + const runGcPlan = async ( + project: McppProjectDiscovery | undefined, + budgetGiB: number, + extra: string, + ): Promise => { + const plan = planClean("cacheGc", { budgetGiB }); + const dialog = extraGcConfirmation(plan, budgetGiB, read("mcpp.cache.gc.confirmAboveGiB")); + // The extra level is asked *before* the plan's own modal, so a refused + // acknowledgement never reaches the one that would have run the command. + // `extraGcConfirmation` already resolved the strings through `t()`. + if (dialog !== undefined) { + const choice = await vscode.window.showWarningMessage( + dialog.title, + { modal: true, detail: formatMessage(dialog.detail, dialog.args) }, + dialog.acknowledge, + ); + if (choice !== dialog.acknowledge) { + return; + } + } + await runPlan(project, plan, extra); + }; + + const requireTrusted = (): boolean => { + if (deps.isTrusted()) { + return true; + } + void vscode.window.showWarningMessage( + t("This workspace is not trusted. mcpp commands that write are disabled until you trust it."), + ); + return false; + }; + + const register = (id: string, handler: (...args: unknown[]) => Promise): void => { + context.subscriptions.push( + vscode.commands.registerCommand(id, async (...args: unknown[]) => { + try { + await handler(...args); + } catch (error) { + const message = error instanceof Error ? error.message : String(error); + deps.output.appendLine(`mcpp: ${message}`); + void vscode.window.showErrorMessage(t("mcpp: {0}", message)); + } + }), + ); + }; + + /** What the view shows, from the same state the commands use. Runs nothing. */ + const panelData = (): CachePanelData => { + const inventory = state.inventory; + const artifacts = state.artifacts; + return { + project: { + available: artifacts !== undefined && artifacts.exists, + note: + artifacts === undefined + ? t("Project artifacts could not be measured.") + : artifacts.exists + ? undefined + : t("No target/ directory"), + totalBytes: artifacts?.totalBytes ?? 0, + files: artifacts?.files ?? 0, + groups: artifacts?.byTopLevel.length ?? 0, + truncated: artifacts?.truncated, + }, + shared: { + available: inventory !== undefined, + note: inventory === undefined ? state.error ?? t("The shared build cache could not be read.") : undefined, + root: inventory?.root, + totalBytes: inventory?.totalBytes ?? 0, + totalEntries: inventory?.totalEntries ?? 0, + byKind: inventory?.byKind ?? [], + buckets: inventory?.ageBuckets ?? [], + top: (inventory?.topLabels ?? []).map((entry) => ({ + label: entry.label, + entries: entry.entries, + bytes: entry.bytes, + oldestAccessed: entry.oldestAccessed, + })), + incomplete: inventory?.incomplete.length ?? 0, + oldestAccessed: timestamp(inventory?.oldestAccessed), + newestAccessed: timestamp(inventory?.newestAccessed), + }, + legacy: legacyForPanel(legacyGate(viewSettings(), state.legacy), state.legacy?.path), + }; + }; + + // `mcpp.cache.autoRefreshSeconds`: re-read while the view is on screen, never + // in an untrusted workspace, and never on top of a read that is still running. + // The tick only redraws: the provider's own read path performs the refresh, so + // one tick costs one round of queries. + const timer = new PollTimer({ + periodMs: 0, + tick: (): void => { + if (viewVisible() && deps.isTrusted()) { + provider?.refresh(); + } + }, + }); + context.subscriptions.push(timer); + const applyTimer = (): void => { + const seconds = viewSettings().autoRefreshSeconds; + const usable = deps.isTrusted() && Number.isFinite(seconds) && seconds > 0; + const decision = refreshTimerDecision(usable ? seconds : 0, viewVisible()); + timer.start(decision.active ? decision.seconds * 1000 : 0); + }; + applyTimer(); + + // The sidebar webview view: `mcpp.cache` is a `"type": "webview"` view, so + // this provider (not a tree) is what draws it. Every destructive action still + // goes through `runPlan` above. + provider = registerCachePanel(context, { + refresh, + read: panelData, + run: async (message) => { + const project = deps.currentProject(); + switch (message.type) { + case "cleanStale": + await runPlan(project, planClean("stale", { staleDays: read("mcpp.cache.staleDays") })); + return; + case "cleanProject": + await runPlan(project, planClean("project")); + return; + case "collect": + await runGcPlan(project, message.budgetGiB, ""); + return; + case "prune": + await runPlan(project, planClean("cachePrune", { pruneAgeDays: read("mcpp.cache.pruneAgeDays") })); + return; + case "cleanLegacy": + await runPlan(project, planClean("cacheLegacy")); + return; + default: + await run(deps, project, ["cache", "verify"], { timeoutMs: CLEAN_TIMEOUT_MS }); + return; + } + }, + showEntry: async (label) => { + await vscode.commands.executeCommand(CACHE_COMMANDS.showEntry, label); + }, + onVisibilityChanged: () => applyTimer(), + }); + + register(CACHE_COMMANDS.refreshStats, async () => { + if (!requireTrusted()) return; + await refresh(); + provider?.refresh(); + }); + + register(CACHE_COMMANDS.showEntry, async (label) => { + if (!requireTrusted()) return; + if (typeof label !== "string" || label.length === 0) { + return; + } + const project = deps.currentProject(); + const result = await run(deps, project, ["cache", "info", label], { timeoutMs: queryTimeoutMs(), quiet: true }); + await preview(t("Cache entry {0}", label), result.stdout.length > 0 ? result.stdout : result.stderr); + }); + + register(CACHE_COMMANDS.cleanStale, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + if (project === undefined) { + void vscode.window.showWarningMessage(t("This workspace has no mcpp.toml.")); + return; + } + const plan = planClean("stale", { staleDays: read("mcpp.cache.staleDays") }); + const dry = await run(deps, project, ["clean", "--dry-run"], { timeoutMs: CLEAN_TIMEOUT_MS, quiet: true }); + await preview(t("mcpp clean --dry-run"), dry.stdout.length > 0 ? dry.stdout : dry.stderr); + await runPlan(project, plan); + }); + + register(CACHE_COMMANDS.cleanProject, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + if (project === undefined) { + void vscode.window.showWarningMessage(t("This workspace has no mcpp.toml.")); + return; + } + const base = planClean("project"); + const alsoCache = t("Also empty the shared build cache"); + // `mcpp.task.confirmClean` answers the same question here as it does on the + // task path. Turning it off skips only *this* modal: choosing to also empty + // the shared cache still escalates through the plan's own level 3. + const choice = read("mcpp.task.confirmClean") + ? await vscode.window.showWarningMessage( + t(base.titleKey), + { modal: true, detail: t(base.detailKey) }, + t("Run"), + alsoCache, + ) + : undefined; + if (read("mcpp.task.confirmClean") && choice === undefined) { + return; + } + const plan = choice === alsoCache ? withSharedCache(base) : base; + if (plan.acknowledge && choice === alsoCache) { + const acknowledge = t("I understand this affects every mcpp project on this machine"); + const second = await vscode.window.showWarningMessage( + t("Confirm once more"), + { modal: true, detail: t(plan.detailKey) }, + acknowledge, + ); + if (second !== acknowledge) { + return; + } + } + const result = await run(deps, project, plan.argv, { timeoutMs: CLEAN_TIMEOUT_MS }); + if (result.exitCode === 0) { + await refresh(); + } else { + void vscode.window.showErrorMessage(t("mcpp {0} failed with exit code {1}", plan.argv.join(" "), result.exitCode)); + } + }); + + register(CACHE_COMMANDS.collect, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + await refresh(); + const total = state.inventory?.totalBytes ?? 0; + const suggested = read("mcpp.cache.gc.defaultBudgetGiB") || Math.max(1, Math.round(total / 1024 ** 3 / 2)); + const input = await vscode.window.showInputBox({ + title: t("Keep the shared build cache under how many GiB?"), + value: String(suggested), + validateInput: (value) => (/^\d+$/.test(value.trim()) ? undefined : t("Enter a whole number of GiB")), + }); + if (input === undefined) { + return; + } + const budgetGiB = Number.parseInt(input.trim(), 10); + // Local LRU projection: an estimate, offered so the budget is chosen with + // numbers rather than guessed. mcpp's own policy decides in the end. + const projection = projectGc(state.entries, budgetGiB * 1024 ** 3); + const estimate = + projection.removed.length === 0 + ? t("Already within {0} GiB.", budgetGiB) + : t("About {0} would be freed ({1} entries).", formatBytes(projection.freedBytes), projection.removed.length); + await runGcPlan(project, budgetGiB, `\n${estimate}`); + }); + + register(CACHE_COMMANDS.prune, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + await runPlan(project, planClean("cachePrune", { pruneAgeDays: read("mcpp.cache.pruneAgeDays") })); + }); + + register(CACHE_COMMANDS.verify, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + const result = await run(deps, project, ["cache", "verify"], { timeoutMs: CLEAN_TIMEOUT_MS }); + if (result.exitCode === 0) { + const text = `${result.stdout}\n${result.stderr}`.trim(); + await preview(t("Cache verification"), text.length === 0 ? t("Every entry matches its manifest.") : text); + } else { + void vscode.window.showErrorMessage(t("mcpp cache verify failed with exit code {0}", result.exitCode)); + } + }); + + register(CACHE_COMMANDS.cleanLegacy, async () => { + if (!requireTrusted()) return; + const project = deps.currentProject(); + await runPlan(project, planClean("cacheLegacy")); + }); + + // First paint: show what the settings allow without running anything heavy. + if (deps.currentProject() !== undefined && read("mcpp.cache.estimateProjectBytes")) { + const project = deps.currentProject(); + if (project !== undefined) { + state.artifacts = estimateArtifacts(project.root); + } + } + provider.refresh(); + updateStatus(); + + // Keep the view, the timer and the status item in step with the settings. + context.subscriptions.push( + vscode.workspace.onDidChangeConfiguration((event) => { + if (event.affectsConfiguration("mcpp.views.cache") || event.affectsConfiguration("mcpp.cache") || event.affectsConfiguration("mcpp.ui.numberFormat")) { + provider?.refresh(); + updateStatus(); + applyTimer(); + } + }), + ); + + return provider; +} + +// ── the self-check's cache snapshot (§8 G9) ────────────────────────────────── + +/** A reading older than this is re-taken rather than reported as current. */ +const SNAPSHOT_FRESH_MS = 60_000; + +let lastSnapshot: { snapshot: CacheSnapshot; at: number } | undefined; + +function setLastCacheSnapshot(snapshot: CacheSnapshot | undefined): void { + lastSnapshot = snapshot === undefined ? undefined : { snapshot, at: Date.now() }; +} + +/** The configured `mcpp.path`, or `mcpp` — the same rule the CLI controller uses. */ +function snapshotExecutable(): string { + const configured = vscode.workspace.getConfiguration("mcpp").get("path", ""); + return configured.trim().length === 0 ? "mcpp" : configured.trim(); +} + +/** + * `showSelfCheck` calls this to fill `buildSelfCheckText`'s `cache` field. + * + * It runs the same read-only `mcpp cache list --format json` the cache view runs + * and reuses that view's own aggregation, so the self-check and the view can + * never disagree. A reading the view took less than a minute ago is reused, so + * opening the self-check does not re-run a query for a number the user just saw. + * + * An untrusted workspace reuses the last reading and never runs `mcpp`; a + * missing `mcpp`, a failed query or an unreadable document all return + * `undefined`, which `buildSelfCheckText` renders as "not read". + * + * The one-line caller change is in the report: + * `cache: await readCacheSnapshot(),` inside the `buildSelfCheckText` call. + */ +export async function readCacheSnapshot(): Promise { + const cached = lastSnapshot; + if (cached !== undefined && Date.now() - cached.at < SNAPSHOT_FRESH_MS) { + return cached.snapshot; + } + if (!vscode.workspace.isTrusted) { + return cached?.snapshot; + } + return readCacheSnapshotNow(); +} + +/** + * Read regardless of what the view last showed: this is the query itself, kept + * separate so a caller with an explicit reason to re-measure can ask for one. + * Read-only, bounded, and never throws. + */ +export async function readCacheSnapshotNow(): Promise { + try { + const result = await runMcpp(vscode.workspace.isTrusted, snapshotExecutable(), ["cache", "list", "--format", "json"], undefined, { + timeoutMs: queryTimeoutMs(), + maxBufferMiB: read("mcpp.runtime.maxOutputMiB"), + }); + if (result === undefined || result.exitCode !== 0) { + return undefined; + } + const parsed = parseCacheList(result.stdout); + if (parsed === undefined) { + return undefined; + } + const inventory = summarizeCache(parsed.root, parsed.entries, { topN: 0, ageBoundaries: [] }); + return cacheSnapshotFrom({ + totalBytes: inventory.totalBytes, + totalEntries: inventory.totalEntries, + incomplete: inventory.incomplete.length, + }); + } catch { + return undefined; + } +} + diff --git a/src/cli/artifacts.ts b/src/cli/artifacts.ts new file mode 100644 index 0000000..eef7073 --- /dev/null +++ b/src/cli/artifacts.ts @@ -0,0 +1,197 @@ +/** + * Size estimate for a project's `target/` directory (plan §3.4.1). + * + * mcpp states that the contents of `target/` are **not an interface**, so this is + * an estimate for the cache view only: it never parses mcpp's fingerprints and + * never guesses which artifacts are stale. The authoritative "what would be + * removed" answer is `mcpp clean --dry-run`. + * + * Pure `node:fs`, never throws, and bounded: a hostile or huge `target/` cannot + * hang the extension host. Symlinks are counted as zero-byte entries and are + * never followed (a link back to an ancestor would otherwise loop forever). + */ + +import { lstatSync, readdirSync } from "node:fs"; +import path from "node:path"; + +import { formatBytes } from "../util/format"; + +export interface ArtifactGroup { + name: string; + bytes: number; + files: number; +} + +export interface ArtifactEstimate { + /** Absolute path of `target/`, whether or not it exists. */ + path: string; + exists: boolean; + totalBytes: number; + files: number; + /** One entry per directory directly under `/target`. */ + byTopLevel: ArtifactGroup[]; + /** Set when the walk stopped early; the numbers are then a floor. */ + truncated?: "entries" | "depth"; +} + +const DEFAULT_MAX_ENTRIES = 200_000; +const DEFAULT_MAX_DEPTH = 6; + +function budget(value: number | undefined, fallback: number): number { + if (value === undefined || !Number.isFinite(value) || value < 0) { + return fallback; + } + return Math.floor(value); +} + +/** + * Walk `/target` with a bounded budget. Never throws. + * + * Returns `exists: false` with zeros when `target/` is missing, is not a + * directory, or is itself a symlink. + */ +export function estimateArtifacts( + projectRoot: string, + options: { maxEntries?: number; maxDepth?: number } = {}, +): ArtifactEstimate { + return measureDirectory(path.join(projectRoot, "target"), options); +} + +/** + * The same bounded walk, for a directory that is already known by path. + * + * The cache view needs it for the pre-v1 cache path `mcpp cache dir` reports + * (plan §3.4 / §8 G6): that directory lives outside the workspace, so it cannot + * be reached through {@link estimateArtifacts}. The same rules apply — bounded, + * never followed through symlinks, and it reports a floor instead of throwing + * when the walk stops early. + */ +export function measureDirectory( + root: string, + options: { maxEntries?: number; maxDepth?: number } = {}, +): ArtifactEstimate { + const maxEntries = budget(options.maxEntries, DEFAULT_MAX_ENTRIES); + const maxDepth = budget(options.maxDepth, DEFAULT_MAX_DEPTH); + + const missing: ArtifactEstimate = { + path: root, + exists: false, + totalBytes: 0, + files: 0, + byTopLevel: [], + }; + let targetStat; + try { + targetStat = lstatSync(root); + } catch { + return missing; + } + // A symlinked `target/` is not followed either, so it reports as absent. + if (!targetStat.isDirectory()) { + return missing; + } + + const byTopLevel: ArtifactGroup[] = []; + let totalBytes = 0; + let files = 0; + let visited = 0; + let truncated: "entries" | "depth" | undefined; + + const add = (group: ArtifactGroup | undefined, bytes: number, count: number): void => { + totalBytes += bytes; + files += count; + if (group !== undefined) { + group.bytes += bytes; + group.files += count; + } + }; + + const hasEntries = (directory: string): boolean => { + try { + return readdirSync(directory, { withFileTypes: true }).length > 0; + } catch { + return false; + } + }; + + const walk = (directory: string, depth: number, group: ArtifactGroup | undefined): void => { + if (truncated === "entries") { + return; + } + if (depth > maxDepth) { + // Only report depth truncation when something was actually left behind. + if (hasEntries(directory)) { + truncated = truncated ?? "depth"; + } + return; + } + let dirents; + try { + dirents = readdirSync(directory, { withFileTypes: true }); + } catch { + // Unreadable directory: tolerate it, the estimate is a floor anyway. + return; + } + for (const dirent of dirents) { + if (visited >= maxEntries) { + truncated = "entries"; + return; + } + visited += 1; + + const full = path.join(directory, dirent.name); + let stat; + try { + stat = lstatSync(full); + } catch { + // Raced with a concurrent `mcpp clean`, or a permission error: skip it. + continue; + } + if (stat.isSymbolicLink()) { + // Never followed; counted as an entry of zero bytes. + add(group, 0, 1); + continue; + } + if (stat.isDirectory()) { + let child = group; + if (depth === 0) { + child = { name: dirent.name, bytes: 0, files: 0 }; + byTopLevel.push(child); + } + walk(full, depth + 1, child); + continue; + } + // Regular files carry a size; fifos/sockets/devices are counted at 0. + add(group, stat.isFile() ? stat.size : 0, 1); + } + }; + + walk(root, 0, undefined); + + byTopLevel.sort( + (left, right) => + right.bytes - left.bytes || (left.name < right.name ? -1 : left.name > right.name ? 1 : 0), + ); + + const estimate: ArtifactEstimate = { + path: root, + exists: true, + totalBytes, + files, + byTopLevel, + }; + if (truncated !== undefined) { + estimate.truncated = truncated; + } + return estimate; +} + +/** One human line for the cache view / status bar, e.g. `"1.43 GiB in 3 groups"`. */ +export function formatArtifactEstimate(estimate: ArtifactEstimate): string { + if (!estimate.exists) { + return "no target/ directory"; + } + const groups = estimate.byTopLevel.length; + const base = `${formatBytes(estimate.totalBytes)} in ${groups} group${groups === 1 ? "" : "s"}`; + return estimate.truncated === undefined ? base : `${base} (truncated: ${estimate.truncated})`; +} diff --git a/src/cli/cache.ts b/src/cli/cache.ts new file mode 100644 index 0000000..addae80 --- /dev/null +++ b/src/cli/cache.ts @@ -0,0 +1,293 @@ +/** + * `mcpp cache …` reading and aggregation (plan §3.4). + * + * Pure functions over captured stdout plus the view model the cache TreeView and + * the statistics webview render. No `vscode` and no process spawning: the caller + * runs `mcpp` (`src/cli/process.ts`) and hands the text in. + * + * Two documents are involved: + * - `mcpp cache list --format json` — a real envelope (`kind: "mcpp.cache"`), + * parsed strictly; a foreign or unknown document is rejected outright; + * - `mcpp cache dir` — human text, so it is parsed leniently and partially. + * + * Everything is defensive: a broken entry is dropped, never thrown. A cache view + * that fails to render is worse than one that renders fewer rows. + */ + +import { ageInDays, bucketIndex, fromUnixSeconds, parseAgeBuckets } from "../util/format"; + +/** Envelope `kind` of `mcpp cache list --format json`. */ +const CACHE_LIST_KIND = "mcpp.cache"; + +/** Fallback `kind` for an entry whose own `kind` is missing or not a string. */ +const UNKNOWN_KIND = "unknown"; + +/** Default number of labels reported by {@link summarizeCache}. */ +const DEFAULT_TOP_N = 5; + +export interface CacheEntry { + accessed?: number; + bytes: number; + complete: boolean; + dir: string; + files?: number; + key: string; + kind: string; + label: string; +} + +export interface CacheInventory { + root: string; + entries: CacheEntry[]; + totalBytes: number; + totalEntries: number; + /** Per-kind totals, largest first. */ + byKind: Array<{ kind: string; entries: number; bytes: number }>; + /** Per-label totals, largest first, capped by `topN`. */ + topLabels: Array<{ label: string; entries: number; bytes: number; oldestAccessed?: number }>; + /** Entries whose `complete` is false. */ + incomplete: CacheEntry[]; + oldestAccessed?: number; + newestAccessed?: number; + /** Age histogram: index i is `[boundaries[i-1], boundaries[i])` days, last bucket is the overflow. */ + ageBuckets: Array<{ fromDays: number; toDays?: number; entries: number; bytes: number }>; +} + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null && !Array.isArray(value); +} + +function nonEmptyString(value: unknown): string | undefined { + return typeof value === "string" && value.length > 0 ? value : undefined; +} + +function finiteNumber(value: unknown): number | undefined { + return typeof value === "number" && Number.isFinite(value) ? value : undefined; +} + +/** Deterministic, locale-independent string ordering. */ +function compareStrings(left: string, right: string): number { + return left < right ? -1 : left > right ? 1 : 0; +} + +function parseCacheEntry(raw: unknown): CacheEntry | undefined { + if (!isRecord(raw)) { + return undefined; + } + const dir = nonEmptyString(raw.dir); + const key = nonEmptyString(raw.key); + const label = nonEmptyString(raw.label); + const bytes = finiteNumber(raw.bytes); + if (dir === undefined || key === undefined || label === undefined || bytes === undefined) { + return undefined; + } + const entry: CacheEntry = { + bytes: Math.max(0, bytes), + // A missing `complete` counts as incomplete: mcpp always emits it, so an + // absent field means a truncated record, which is exactly what + // "incomplete" should surface to the user (`mcpp cache verify`). + complete: raw.complete === true, + dir, + key, + kind: typeof raw.kind === "string" ? raw.kind : UNKNOWN_KIND, + label, + }; + const accessed = finiteNumber(raw.accessed); + if (accessed !== undefined) { + entry.accessed = accessed; + } + const files = finiteNumber(raw.files); + if (files !== undefined) { + entry.files = files; + } + return entry; +} + +/** + * Parse `mcpp cache list --format json` stdout. + * `undefined` when it is not that document (non-JSON, foreign `kind`, bad shape). + */ +export function parseCacheList(stdout: string): { root: string; entries: CacheEntry[] } | undefined { + let document: unknown; + try { + document = JSON.parse(stdout); + } catch { + return undefined; + } + if (!isRecord(document) || document.kind !== CACHE_LIST_KIND) { + return undefined; + } + const data = document.data; + if (!isRecord(data) || !Array.isArray(data.entries)) { + return undefined; + } + const entries: CacheEntry[] = []; + for (const raw of data.entries) { + const entry = parseCacheEntry(raw); + if (entry !== undefined) { + entries.push(entry); + } + } + return { root: typeof data.root === "string" ? data.root : "", entries }; +} + +/** + * Parse `mcpp cache dir` stdout: + * + * ``` + * /home/u/.mcpp/build-cache/v1 + * legacy (unused, removable with `mcpp cache clean --legacy`): /home/u/.mcpp/bmi + * ``` + * + * The legacy line is absent when there is no pre-v1 cache. The legacy path is + * whatever follows the **last** `": "` on that line — the backticked command name + * in the parenthetical must never be mistaken for a path. + */ +export function parseCacheDir(stdout: string): { root?: string; legacyPath?: string } { + let root: string | undefined; + let legacyPath: string | undefined; + for (const line of stdout.split(/\r?\n/)) { + const trimmed = line.trim(); + if (trimmed.length === 0) { + continue; + } + if (/^legacy\b/i.test(trimmed)) { + const separator = trimmed.lastIndexOf(": "); + const candidate = separator >= 0 ? trimmed.slice(separator + 2).trim() : ""; + if (candidate.length > 0) { + legacyPath = candidate; + } + continue; + } + if (root === undefined) { + root = trimmed; + } + } + const result: { root?: string; legacyPath?: string } = {}; + if (root !== undefined) { + result.root = root; + } + if (legacyPath !== undefined) { + result.legacyPath = legacyPath; + } + return result; +} + +/** + * Aggregate a cache listing into what the views need. + * + * `ageBoundaries` come from `mcpp.views.cache.ageBuckets` as strings (`"1d"`, + * `"7d"`, `"30d"`); see `parseAgeBuckets`. Entries without a usable `accessed` + * timestamp are excluded from the histogram and from oldest/newest, because + * their age is unknown — guessing would promise reclaimable space mcpp may keep. + */ +export function summarizeCache( + root: string, + entries: readonly CacheEntry[], + options: { topN?: number; ageBoundaries?: readonly string[] } = {}, +): CacheInventory { + const topN = options.topN === undefined ? DEFAULT_TOP_N : Math.max(0, Math.floor(options.topN)); + const boundaries = parseAgeBuckets(options.ageBoundaries); + const now = new Date(); + + const byKindTotals = new Map(); + const labelTotals = new Map< + string, + { entries: number; bytes: number; oldestAccessed?: number } + >(); + const incomplete: CacheEntry[] = []; + + const ageBuckets: CacheInventory["ageBuckets"] = []; + for (let index = 0; index <= boundaries.length; index += 1) { + const bucket: CacheInventory["ageBuckets"][number] = { + fromDays: index === 0 ? 0 : boundaries[index - 1], + entries: 0, + bytes: 0, + }; + if (index < boundaries.length) { + bucket.toDays = boundaries[index]; + } + ageBuckets.push(bucket); + } + + let totalBytes = 0; + let oldestAccessed: number | undefined; + let newestAccessed: number | undefined; + + for (const entry of entries) { + const bytes = Number.isFinite(entry.bytes) ? Math.max(0, entry.bytes) : 0; + totalBytes += bytes; + + const kindTotals = byKindTotals.get(entry.kind) ?? { entries: 0, bytes: 0 }; + kindTotals.entries += 1; + kindTotals.bytes += bytes; + byKindTotals.set(entry.kind, kindTotals); + + const labelEntry = labelTotals.get(entry.label) ?? { entries: 0, bytes: 0 }; + labelEntry.entries += 1; + labelEntry.bytes += bytes; + if (entry.accessed !== undefined && Number.isFinite(entry.accessed)) { + if (labelEntry.oldestAccessed === undefined || entry.accessed < labelEntry.oldestAccessed) { + labelEntry.oldestAccessed = entry.accessed; + } + if (oldestAccessed === undefined || entry.accessed < oldestAccessed) { + oldestAccessed = entry.accessed; + } + if (newestAccessed === undefined || entry.accessed > newestAccessed) { + newestAccessed = entry.accessed; + } + const at = fromUnixSeconds(entry.accessed); + if (at !== undefined) { + const bucket = ageBuckets[bucketIndex(ageInDays(at, now), boundaries)]; + bucket.entries += 1; + bucket.bytes += bytes; + } + } + labelTotals.set(entry.label, labelEntry); + + if (!entry.complete) { + incomplete.push(entry); + } + } + + const byKind = [...byKindTotals.entries()] + .map(([kind, totals]) => ({ kind, entries: totals.entries, bytes: totals.bytes })) + .sort( + (left, right) => + right.bytes - left.bytes || + right.entries - left.entries || + compareStrings(left.kind, right.kind), + ); + + const rankedLabels = [...labelTotals.entries()] + .map(([label, totals]) => ({ + label, + entries: totals.entries, + bytes: totals.bytes, + ...(totals.oldestAccessed === undefined ? {} : { oldestAccessed: totals.oldestAccessed }), + })) + .sort( + (left, right) => + right.bytes - left.bytes || + right.entries - left.entries || + compareStrings(left.label, right.label), + ); + + const inventory: CacheInventory = { + root, + entries: [...entries], + totalBytes, + totalEntries: entries.length, + byKind, + topLabels: rankedLabels.slice(0, topN), + incomplete, + ageBuckets, + }; + if (oldestAccessed !== undefined) { + inventory.oldestAccessed = oldestAccessed; + } + if (newestAccessed !== undefined) { + inventory.newestAccessed = newestAccessed; + } + return inventory; +} diff --git a/src/cli/clean.ts b/src/cli/clean.ts new file mode 100644 index 0000000..f2be9a6 --- /dev/null +++ b/src/cli/clean.ts @@ -0,0 +1,242 @@ +/** + * Cleanup, as plans rather than as calls. + * + * Every destructive action this extension can run is described here: the exact + * argv, how much confirmation it needs, and whether a preview must be shown + * first. Keeping it in one pure table means the UI cannot invent a sixth level + * of danger, and the tests can assert the policy instead of the wording. + * + * The policy (from the plan, §3.4.3): + * + * | level | what | confirmation | + * |---|---|---| + * | 0 | read-only (`cache list`/`dir`/`info`/`verify`) | none | + * | 1 | project body (`mcpp clean`) | modal, with the measured size | + * | 2 | budget/targeted (`cache gc`, `cache prune`, `cache clean --deps/--std`) | preview, then modal | + * | 3 | everything (`cache clean --all`) | preview, modal, then a second acknowledgement | + * + * The user asked for `cache clean --all` to be reachable — so it is — but it is + * the only level-3 action, and its text names every project on the machine. + */ + +export type CleanAction = + | "project" + | "stale" + | "cacheGc" + | "cachePrune" + | "cacheDeps" + | "cacheStd" + | "cacheAll" + | "cacheLegacy" + | "cacheVerify" + | "cacheList"; + +export interface CleanOptions { + /** `mcpp clean --stale --older-than d`; 0 means "keep none". */ + staleDays?: number; + /** `mcpp cache gc --max-size GiB`; 0 means "the user types a budget". */ + budgetGiB?: number; + /** `mcpp cache prune --older-than d`. */ + pruneAgeDays?: number; +} + +export interface CleanPlan { + action: CleanAction; + /** The mcpp subcommand, for logging: `clean` or `cache`. */ + group: "clean" | "cache"; + argv: readonly string[]; + /** 0 read-only, 1 modal, 2 preview+modal, 3 preview+modal+acknowledge. */ + level: 0 | 1 | 2 | 3; + /** A `--dry-run`-style pass the UI must show before asking. */ + preview: boolean; + /** A second, explicit acknowledgement (a checkbox) is required. */ + acknowledge: boolean; + /** English key for the dialogue title. */ + titleKey: string; + /** English key for the body; the caller adds the measured figures. */ + detailKey: string; + /** This action is refused when the workspace is untrusted. */ + requiresTrust: boolean; +} + +function staleDaysOf(options: CleanOptions): number { + const days = options.staleDays ?? 3; + return Number.isFinite(days) ? Math.max(0, Math.round(days)) : 3; +} + +export function planClean(action: CleanAction, options: CleanOptions = {}): CleanPlan { + switch (action) { + case "project": + return { + action, + group: "clean", + argv: ["clean"], + level: 1, + preview: false, + acknowledge: false, + titleKey: "Remove the whole target/ directory?", + detailKey: "This deletes every build directory of this project. The next build starts from scratch. The shared build cache is not touched.", + requiresTrust: true, + }; + case "stale": + return { + action, + group: "clean", + argv: ["clean", "--stale", "--older-than", `${staleDaysOf(options)}d`], + level: 2, + preview: true, + acknowledge: false, + titleKey: "Remove build directories mcpp no longer considers current?", + detailKey: "Directories written in the last {0} day(s) are kept. mcpp decides which ones are stale; the preview above is its own list.", + requiresTrust: true, + }; + case "cacheGc": { + const budget = options.budgetGiB ?? 0; + const argv = budget > 0 ? ["cache", "gc", "--max-size", `${budget}GiB`] : ["cache", "gc"]; + return { + action, + group: "cache", + argv, + level: 2, + preview: true, + acknowledge: false, + titleKey: "Collect the shared build cache to a budget?", + detailKey: "mcpp drops least-recently-used entries until the cache fits. Projects that used a dropped entry rebuild it.", + requiresTrust: true, + }; + } + case "cachePrune": { + const days = options.pruneAgeDays ?? 30; + return { + action, + group: "cache", + argv: ["cache", "prune", "--older-than", `${Number.isFinite(days) ? Math.max(1, Math.round(days)) : 30}d`], + level: 2, + preview: true, + acknowledge: false, + titleKey: "Drop cache entries that have not been used for a while?", + detailKey: "Entries unused for longer than {0} day(s) are removed. Projects that used one rebuild it.", + requiresTrust: true, + }; + } + case "cacheDeps": + return { + action, + group: "cache", + argv: ["cache", "clean", "--deps"], + level: 2, + preview: true, + acknowledge: false, + titleKey: "Drop every package entry from the shared cache?", + detailKey: "Every mcpp project on this machine rebuilds its dependencies afterwards. Standard library module entries are kept.", + requiresTrust: true, + }; + case "cacheStd": + return { + action, + group: "cache", + argv: ["cache", "clean", "--std"], + level: 2, + preview: true, + acknowledge: false, + titleKey: "Drop every standard library module entry from the shared cache?", + detailKey: "Every mcpp project on this machine re-prepares the standard library module afterwards. Package entries are kept.", + requiresTrust: true, + }; + case "cacheAll": + return { + action, + group: "cache", + argv: ["cache", "clean", "--all"], + level: 3, + preview: true, + acknowledge: true, + titleKey: "Drop the entire shared build cache?", + detailKey: "Package and standard library entries go. Every mcpp project on this machine rebuilds from scratch afterwards.", + requiresTrust: true, + }; + case "cacheLegacy": + return { + action, + group: "cache", + argv: ["cache", "clean", "--legacy"], + level: 2, + preview: false, + acknowledge: false, + titleKey: "Remove the unused pre-v1 cache?", + detailKey: "mcpp no longer reads $MCPP_HOME/bmi. Nothing is rebuilt because nothing uses it.", + requiresTrust: true, + }; + case "cacheVerify": + return { + action, + group: "cache", + argv: ["cache", "verify"], + level: 0, + preview: false, + acknowledge: false, + titleKey: "Verify the shared build cache", + detailKey: "Every entry's manifest is checked against the files on disk.", + requiresTrust: true, + }; + default: + return { + action: "cacheList", + group: "cache", + argv: ["cache", "list", "--format", "json"], + level: 0, + preview: false, + acknowledge: false, + titleKey: "Read the shared build cache", + detailKey: "Nothing is removed.", + requiresTrust: true, + }; + } +} + +/** True when `mcpp clean`'s global cache also goes — the option the UI keeps un-ticked. */ +export function withSharedCache(plan: CleanPlan): CleanPlan { + if (plan.action !== "project") { + return plan; + } + return { + ...plan, + argv: [...plan.argv, "--bmi-cache"], + level: 3, + acknowledge: true, + detailKey: "This also empties the shared build cache, so every mcpp project on this machine rebuilds from scratch.", + }; +} + +/** The single destructive action that may be shortened to one confirmation. */ +export function planProblems(): string[] { + const problems: string[] = []; + const actions: CleanAction[] = [ + "project", + "stale", + "cacheGc", + "cachePrune", + "cacheDeps", + "cacheStd", + "cacheAll", + "cacheLegacy", + "cacheVerify", + "cacheList", + ]; + for (const action of actions) { + const plan = planClean(action); + if (plan.requiresTrust === false) { + problems.push(`${action} does not require a trusted workspace`); + } + if (plan.level >= 2 && !plan.preview && plan.action !== "cacheLegacy") { + problems.push(`${action} must be previewed before it runs`); + } + if (plan.level === 3 && !plan.acknowledge) { + problems.push(`${action} must require a second acknowledgement`); + } + if (plan.argv.some((part) => part.includes(" "))) { + problems.push(`${action} passes an argument containing a space`); + } + } + return problems; +} diff --git a/src/cli/controller.ts b/src/cli/controller.ts new file mode 100644 index 0000000..087116c --- /dev/null +++ b/src/cli/controller.ts @@ -0,0 +1,1160 @@ +import { existsSync } from "node:fs"; +import { join } from "node:path"; +import process from "node:process"; + +import * as vscode from "vscode"; + +import { + hostDefaultToolchains, + mcppCommandArguments, + normalizeToolchainSpec, + parseToolchainList, + toolchainInstallKind, + toolchainSpecTargetHint, + type ToolchainInventory, + type ToolchainItem, +} from "./toolchain"; +import { + discoveryBoundaryOf, + type DiscoveryBoundary, + type McppProjectDiscovery, +} from "../projects/discovery"; +import { updateEditorTitleButtonsContext } from "../projects/context"; +import { createLogger, type Logger } from "../util/log"; +import { runProcess } from "./process"; +import { + McppOperationRegistry, + classifyTaskExit, + projectTaskPlan, + TASK_ARGUMENT_SETTINGS, + shouldRefreshLanguageServerAfterTask, + type ProjectTaskKind, + type TaskCompletion, +} from "./tasks"; +import { classifyExit, explainHint, type McppFailureKind, type McppOutcome } from "./errors"; +import { statusBarBackgroundColour } from "./statusBar"; +import { CLI_COMMANDS } from "../commands/ids"; +import { QUICK_MENU_GROUPS, quickMenuIconAsset, quickMenuItems, quickMenuStatusText } from "../commands/menu"; +import { read } from "../config/access"; +import { t } from "../i18n/t"; +import { controllerLabels } from "./labels"; +import { runNewProjectFlow, validateNewProjectName } from "./newProject"; + +export interface McppCliControllerOptions { + output: vscode.OutputChannel; + /** + * The extension's own directory, for the assets that cannot be a `ThemeIcon` — + * today only the coloured quick menu icons, which VS Code paints as an image + * because it drops a `ThemeIcon`'s colour in a quick pick. + */ + extensionUri: vscode.Uri; + currentProject: () => McppProjectDiscovery | undefined; + afterProjectTask: ( + project: McppProjectDiscovery, + kind: ProjectTaskKind, + completion: TaskCompletion, + ) => Promise; + isTrusted: () => boolean; + /** + * `mcpp.ui.statusBar.showLanguageServer`: one short line describing the C++ + * Modules state, or `undefined` when there is nothing to show. A callback + * instead of an import so this controller never depends on `src/mcppls/**`; + * the extension layer owns the bridge and passes it in. + */ + languageServerSummary?: () => string | undefined; +} + +interface ToolchainPickItem extends vscode.QuickPickItem { + spec?: string; + toolchain?: ToolchainItem; + customInput?: boolean; +} + +type OperationToken = object; + +/** Where the generated quick menu icons live, under the extension root. */ +const QUICK_MENU_ICON_DIRECTORY = "media/quick-menu"; + +export interface ProjectTaskRunOptions { + /** Set to false when the caller performs its own post-task action. */ + notify?: boolean; +} + +function taskScope(root: string): vscode.WorkspaceFolder | vscode.TaskScope { + return vscode.workspace.getWorkspaceFolder(vscode.Uri.file(root)) + ?? vscode.TaskScope.Workspace; +} + +function workingDirectory(project: McppProjectDiscovery | undefined): string { + if (project !== undefined) { + return project.root; + } + return vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? process.cwd(); +} + +function commandLine(executable: string, args: string[]): string { + return [executable, ...args].join(" "); +} + +// ─── pure policy ──────────────────────────────────────────────────────────── +// +// Every decision a setting makes is computed by a pure function in this block, +// so `test/cli/controller.*.test.ts` can assert the decision without an editor. +// The class below only executes what these functions decide. + +export type TaskRevealSetting = "always" | "onFailure" | "never"; + +export interface TaskTerminalUi { + /** `mcpp.task.revealTerminal`. */ + reveal: TaskRevealSetting; + /** `mcpp.task.focusTerminal`: hand keyboard focus to the task terminal. */ + focus: boolean; + /** `mcpp.task.clearTerminal`: clear the panel before the command runs. */ + clearBeforeRun: boolean; +} + +export function taskTerminalUi( + revealTerminal: unknown, + focusTerminal: unknown, + clearTerminal: unknown, +): TaskTerminalUi { + return { + reveal: + revealTerminal === "never" || revealTerminal === "onFailure" ? revealTerminal : "always", + focus: focusTerminal === true, + clearBeforeRun: clearTerminal !== false, + }; +} + +/** `workbench.action.terminal.*` commands to run once the task has finished. */ +export function terminalCommandsAfterTask(ui: TaskTerminalUi, failed: boolean): readonly string[] { + // VS Code has no "reveal without focusing" command, so the one command below + // is both the reveal and the focus for the failure-only setting. + return failed && ui.reveal === "onFailure" ? ["workbench.action.terminal.focus"] : []; +} + +/** The problem matcher `package.json` must contribute under `contributes.problemMatchers`. */ +export const PROBLEM_MATCHER_NAME = "$mcpp"; + +export function problemMatchersFor(enabled: unknown): readonly string[] { + return enabled === false ? [] : [PROBLEM_MATCHER_NAME]; +} + +/** + * `mcpp.task.confirmClean`: this decides only the controller's own prompt for + * `mcpp.clean`. The cleanup plan (`src/cli/clean.ts`) keeps its own level-2/3 + * confirmations, which this setting can never remove. + */ +export function cleanConfirmationRequired(confirmClean: unknown): boolean { + return confirmClean !== false; +} + +export type ConfirmationStrength = "notice" | "modal"; + +export interface ConfirmationPolicy { + installToolchain: ConfirmationStrength; + globalDefault: ConfirmationStrength; +} + +/** + * `mcpp.ui.confirmDestructiveOnly` (default true) reserves a modal for actions + * that cannot be undone. Turning it off escalates these two undoable prompts + * from a dismissible notification to a modal — the prompt, its text and its + * buttons are identical in both modes, so the setting can only ask *more* + * insistently, never less often. + */ +export function confirmationPolicy(confirmDestructiveOnly: unknown): ConfirmationPolicy { + const strength: ConfirmationStrength = confirmDestructiveOnly === false ? "modal" : "notice"; + return { installToolchain: strength, globalDefault: strength }; +} + +/** `mcpp.ui.statusBar.showLanguageServer`: the suffix the status item gains. */ +export function languageServerStatusSuffix(show: unknown, summary: string | undefined): string | undefined { + if (show !== true) { + return undefined; + } + const text = summary?.trim(); + return text === undefined || text.length === 0 ? undefined : text; +} + +export type SuccessReport = "silent" | "statusBar" | "toast"; + +/** `mcpp.ui.notifications.success`; only a *successful* result consults this. */ +export function successReportOf(value: unknown): SuccessReport { + return value === "silent" || value === "toast" ? value : "statusBar"; +} + +/** + * `mcpp.ui.notifications.dedupeMinutes`: true when the same message may be + * shown again. `0` (or an unusable value) shows every notification. + */ +export function dedupeAllows(lastAt: number | undefined, now: number, dedupeMinutes: unknown): boolean { + if (typeof dedupeMinutes !== "number" || !Number.isFinite(dedupeMinutes) || dedupeMinutes <= 0) { + return true; + } + if (typeof lastAt !== "number" || !Number.isFinite(lastAt)) { + return true; + } + return now - lastAt >= dedupeMinutes * 60_000; +} + +export const STATUS_BAR_SUCCESS_MAX = 60; + +/** A status bar item is a label, not a paragraph. */ +export function statusBarSuccessText(message: string): string { + const single = message.replace(/\s+/g, " ").trim(); + return single.length <= STATUS_BAR_SUCCESS_MAX + ? single + : `${single.slice(0, STATUS_BAR_SUCCESS_MAX - 1)}…`; +} + +export interface FailureAdvice { + kind: McppFailureKind; + exitCode: number; + /** `mcpp self explain

`, when the output or code names a diagnostic. */
+  hint?: string;
+}
+
+/**
+ * `src/cli/errors.ts` (SPEC-003) applied to a failed run: the failure kind that
+ * picks the guidance, plus the `mcpp self explain` follow-up when there is a
+ * diagnostic code to explain.
+ */
+export function failureAdvice(args: readonly string[], exitCode: number, output: string): FailureAdvice {
+  const outcome: McppOutcome = { ...classifyExit(exitCode, args), detail: output };
+  return { kind: outcome.kind, exitCode: outcome.exitCode, hint: explainHint(outcome) };
+}
+
+/** The exit-code-specific next step, or `undefined` to keep the caller's message. */
+function failureGuidanceText(kind: McppFailureKind): string | undefined {
+  switch (kind) {
+    case "usage":
+      return t("mcpp rejected the command line; check the arguments and run it from the project root.");
+    case "environment":
+      return t("mcpp is installed but the environment is not ready; run `mcpp self doctor` to see what is missing.");
+    case "internal":
+      return t("mcpp reported an internal error; re-run with the mcpp output channel open and report it.");
+    case "unknown-command":
+      return t("This mcpp build does not recognise that command; update mcpp or check the spelling.");
+    case "build-failed":
+      return t("The program did not build; see the task terminal for the compiler output.");
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The `vscode`-side read of `mcpp.project.discoveryBoundary`. `extension.ts`
+ * passes the result into `findNearestMcppProject`, whose walk stays pure. The
+ * resource is the workspace folder, because the setting is resource-scoped.
+ */
+export function discoveryBoundaryFromSettings(resource?: vscode.Uri): DiscoveryBoundary {
+  return discoveryBoundaryOf(read("mcpp.project.discoveryBoundary", resource));
+}
+
+const SUCCESS_STATUS_MS = 6000;
+
+export class McppCliController {
+  private readonly status: vscode.StatusBarItem;
+
+  private readonly operations = new McppOperationRegistry();
+
+  /** `mcpp.log.level` decides what reaches the `mcpp` channel; see `src/util/log.ts`. */
+  private readonly logger: Logger;
+
+  /** `mcpp.ui.notifications.dedupeMinutes`: message signature -> last shown (ms). */
+  private readonly lastNotified = new Map();
+
+  /** Reverts the transient success text in the status item. */
+  private statusRevert: ReturnType | undefined;
+
+  public constructor(private readonly options: McppCliControllerOptions) {
+    this.status = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 40);
+    this.status.command = CLI_COMMANDS.showMenu;
+    this.logger = createLogger(this.options.output, () => read("mcpp.log.level"));
+    this.applyStatusBar();
+  }
+
+  public register(): vscode.Disposable[] {
+    this.applyStatusBar();
+    const applyEditorTitleButtons = (): void => {
+      void updateEditorTitleButtonsContext({
+        enabled: () => read("mcpp.task.editorTitleButtons"),
+        setContextValue: (key, value) => vscode.commands.executeCommand("setContext", key, value),
+      }).catch(() => undefined);
+    };
+    applyEditorTitleButtons();
+    const disposables: vscode.Disposable[] = [
+      vscode.workspace.onDidChangeConfiguration((event) => {
+        if (event.affectsConfiguration("mcpp.ui.statusBar")) {
+          this.applyStatusBar();
+        }
+        if (event.affectsConfiguration("mcpp.task.editorTitleButtons")) {
+          applyEditorTitleButtons();
+        }
+      }),
+      this.status,
+      vscode.commands.registerCommand(CLI_COMMANDS.showMenu, this.guarded(() => this.showMenu())),
+      vscode.commands.registerCommand(CLI_COMMANDS.newProject, this.guarded(() => this.newProject())),
+      vscode.commands.registerCommand(CLI_COMMANDS.build, this.guarded(() => this.runProjectTask("build"))),
+      vscode.commands.registerCommand(CLI_COMMANDS.run, this.guarded(() => this.runProjectTask("run"))),
+      vscode.commands.registerCommand(CLI_COMMANDS.test, this.guarded(() => this.runProjectTask("test"))),
+      vscode.commands.registerCommand(CLI_COMMANDS.clean, this.guarded(() => this.runProjectTask("clean"))),
+      vscode.commands.registerCommand(CLI_COMMANDS.showToolchains, this.guarded(() => this.showToolchains())),
+      vscode.commands.registerCommand(CLI_COMMANDS.installToolchain, this.guarded(() => this.installToolchain())),
+      vscode.commands.registerCommand(CLI_COMMANDS.selectDefaultToolchain, this.guarded(() => this.selectDefaultToolchain())),
+      vscode.window.onDidChangeActiveTextEditor(() => this.refreshStatus()),
+      vscode.workspace.onDidChangeWorkspaceFolders(() => this.refreshStatus()),
+    ];
+    this.refreshStatus();
+    return disposables;
+  }
+
+  public refreshStatus(): void {
+    if (this.options.currentProject() === undefined) {
+      this.status.hide();
+      return;
+    }
+    this.applyStatusBar();
+  }
+
+  public isBusy(): boolean {
+    return this.operations.hasActive();
+  }
+
+  public async runProjectTask(
+    kind: ProjectTaskKind,
+    options: ProjectTaskRunOptions = {},
+  ): Promise {
+    const project = this.requireProject();
+    if (project === undefined || !this.requireTrusted()) {
+      return undefined;
+    }
+
+    // `mcpp.task.confirmClean`: one prompt for this entry point; the cleanup
+    // plan's own level-2/3 confirmations are untouched by it.
+    if (kind === "clean" && cleanConfirmationRequired(read("mcpp.task.confirmClean", vscode.Uri.file(project.root)))) {
+      const labels = controllerLabels();
+      const choice = await vscode.window.showWarningMessage(
+        t("Delete the target/ directory of this project: {0}/target", project.root),
+        { modal: true, detail: t("This does not clean the global BMI cache.") },
+        labels.confirmClean,
+      );
+      if (choice !== labels.confirmClean) {
+        return undefined;
+      }
+    }
+
+    // `mcpp.runtime.concurrency` picks the mutual-exclusion scope: one task at a
+    // time per project (the default), or one task at a time for the whole window.
+    const globalScope = read("mcpp.runtime.concurrency") === "global";
+    const token: OperationToken = {};
+    const active = globalScope
+      ? this.operations.beginGlobal(token)
+      : this.operations.beginProject(project.root, token);
+    if (active !== undefined) {
+      const labels = controllerLabels();
+      const choice = await vscode.window.showWarningMessage(
+        t("An mcpp operation is already running; not starting {0} now.", kind),
+        labels.showTasks,
+      );
+      if (choice === labels.showTasks) {
+        await vscode.commands.executeCommand("workbench.action.tasks.showTasks");
+      }
+      return undefined;
+    }
+
+    let completion: TaskCompletion | undefined;
+    try {
+      const plan = projectTaskPlan(kind, read(TASK_ARGUMENT_SETTINGS[kind]));
+      completion = await this.executeTask(
+        project.root,
+        this.mcppExecutable(project),
+        plan.title,
+        plan.args,
+      );
+      this.appendTaskCompletion(project.root, plan.title, plan.args, completion);
+    } finally {
+      if (globalScope) {
+        this.operations.finishGlobal(token);
+      } else {
+        this.operations.finishProject(project.root, token);
+      }
+    }
+
+    if (options.notify !== false
+      && completion !== undefined
+      && shouldRefreshLanguageServerAfterTask(kind, completion)) {
+      await this.options.afterProjectTask(project, kind, completion);
+    }
+    return completion;
+  }
+
+  public async showToolchains(): Promise {
+    if (!this.requireTrusted()) {
+      return;
+    }
+    const project = this.options.currentProject();
+    const inventory = await this.readToolchainInventory(project);
+    if (inventory === undefined) {
+      return;
+    }
+
+    const items = this.inventoryItems(inventory, false, project);
+    if (items.length === 0) {
+      await vscode.window.showInformationMessage(
+        t("mcpp listed no usable toolchain; see the raw result in the mcpp output channel."),
+      );
+      return;
+    }
+    await vscode.window.showQuickPick(items, {
+      title: t("mcpp toolchains and targets"),
+      placeHolder: t("Read-only view of what mcpp currently resolves"),
+      matchOnDescription: true,
+      matchOnDetail: true,
+    });
+  }
+
+  public async installToolchain(): Promise {
+    if (!this.requireTrusted()) {
+      return;
+    }
+    const project = this.options.currentProject();
+    const inventory = await this.readToolchainInventory(project);
+    const spec = await this.pickInstallSpec(inventory);
+    if (spec === undefined) {
+      return;
+    }
+    const installKind = toolchainInstallKind(spec);
+    const targetHint = toolchainSpecTargetHint(spec);
+    const labels = controllerLabels();
+    const confirmLabel = installKind === "system-detect" ? labels.confirmDetect : labels.confirmInstall;
+    const confirmation = installKind === "system-detect"
+      ? t("mcpp will detect the system MSVC ({0}).", spec)
+      : targetHint === "target"
+        ? t("The compatible spec {0}, which may carry target semantics, is handed to mcpp to install, and mcpp validates it in the end.", spec)
+        : installKind === "managed-target"
+          ? t("The compatible spec {0} carrying target semantics is handed to mcpp to install.", spec)
+          : t("mcpp toolchain {0} is installed (no target specified, the host target is used).", spec);
+    const detail = installKind === "system-detect"
+      ? t("mcpp does not download or install MSVC; it detects Visual Studio and points to the official installation guide when it is missing.")
+      : targetHint === "target"
+        ? t("mcpp decides whether the compiler prefix is a valid triple; when it is, it may download a larger toolchain package for that target.")
+        : installKind === "managed-target"
+          ? t("mcpp normalises the compatible spelling and may download a larger toolchain package for that target.")
+          : t("The installation may download a large toolchain package and modifies the mcpp global cache.");
+
+    const policy = confirmationPolicy(read("mcpp.ui.confirmDestructiveOnly"));
+    const choice = await vscode.window.showWarningMessage(
+      confirmation,
+      this.warningOptions(policy.installToolchain, detail),
+      confirmLabel,
+    );
+    if (choice !== confirmLabel) {
+      return;
+    }
+
+    const token: OperationToken = {};
+    const active = this.operations.beginGlobal(token);
+    if (active !== undefined) {
+      const duplicateChoice = await vscode.window.showWarningMessage(
+        t("An mcpp operation is already running."),
+        labels.showTasks,
+      );
+      if (duplicateChoice === labels.showTasks) {
+        await vscode.commands.executeCommand("workbench.action.tasks.showTasks");
+      }
+      return;
+    }
+
+    const taskTitle = installKind === "system-detect"
+      ? t("mcpp: detect system MSVC ({0})", spec)
+      : t("mcpp: install toolchain {0}", spec);
+    try {
+      const installArgs = mcppCommandArguments("toolchain", "install", spec);
+      const completion = await this.executeTask(
+        workingDirectory(project),
+        this.mcppExecutable(project),
+        taskTitle,
+        installArgs,
+      );
+      this.appendTaskCompletion(
+        workingDirectory(project),
+        taskTitle,
+        installArgs,
+        completion,
+      );
+      if (completion.state !== "succeeded") {
+        return;
+      }
+    } finally {
+      this.operations.finishGlobal(token);
+    }
+
+    if (installKind === "managed-target") {
+      this.reportSuccess(t("mcpp finished {0}. This first release does not change the target default; to set one, use the mcpp CLI with --target.", spec));
+      return;
+    }
+
+    const refreshed = await this.readToolchainInventory(project);
+    const defaultChoice = await vscode.window.showInformationMessage(
+      installKind === "system-detect"
+        ? t("MSVC detection finished. Choose a global default from the latest list?")
+        : t("Toolchain {0} installed. Choose a global default from the latest list?", spec),
+      labels.chooseGlobalDefault,
+    );
+    if (defaultChoice === labels.chooseGlobalDefault && refreshed !== undefined) {
+      await this.selectDefaultToolchainFromInventory(project, refreshed);
+    }
+  }
+
+  public async selectDefaultToolchain(): Promise {
+    if (!this.requireTrusted()) {
+      return;
+    }
+    const project = this.options.currentProject();
+    const inventory = await this.readToolchainInventory(project);
+    if (inventory !== undefined) {
+      await this.selectDefaultToolchainFromInventory(project, inventory);
+    }
+  }
+
+  private async selectDefaultToolchainFromInventory(
+    project: McppProjectDiscovery | undefined,
+    inventory: ToolchainInventory,
+  ): Promise {
+    const installed = hostDefaultToolchains(inventory);
+    if (installed.length === 0) {
+      await vscode.window.showWarningMessage(
+        t("No installed toolchain is usable for the host target, so a global default cannot be set here. For target-specific toolchains use the mcpp CLI; on Windows install Visual Studio first."),
+      );
+      return;
+    }
+
+    const items: ToolchainPickItem[] = installed.map((toolchain) => ({
+      label: `${toolchain.effective ? "$(check) " : ""}${toolchain.spec}`,
+      description: toolchain.source === "system" ? t("System toolchain (mcpp only detects it)") : t("Toolchain managed by mcpp"),
+      detail: toolchain.effective ? t("Effective toolchain of this project") : undefined,
+      spec: toolchain.spec,
+      toolchain,
+    }));
+    const picked = await vscode.window.showQuickPick(items, {
+      title: t("Choose the mcpp global default toolchain"),
+      placeHolder: this.isNestedWorkspaceProject(project)
+        ? t("The project root sits below the VS Code folder; the real build resolution is whatever mcpp reports")
+        : inventory.projectOverridesGlobal
+          ? t("The project currently overrides the global default; this only changes the current mcpp global configuration")
+          : t("Choosing here only changes the mcpp global configuration; it does not build the project"),
+      matchOnDescription: true,
+      matchOnDetail: true,
+    });
+    if (picked?.spec === undefined) {
+      return;
+    }
+
+    const defaultPolicy = confirmationPolicy(read("mcpp.ui.confirmDestructiveOnly"));
+    const warningLabels = controllerLabels();
+    const choice = await vscode.window.showWarningMessage(
+      t("The global default pair is set to {0} + host target. The mcpp.toml/target configuration of the current project can still override it.", picked.spec),
+      this.warningOptions(
+        defaultPolicy.globalDefault,
+        t("mcpp also clears the global default_target; the configuration file location is decided by the current mcpp installation and MCPP_HOME."),
+      ),
+      warningLabels.confirmDefault,
+    );
+    if (choice !== warningLabels.confirmDefault) {
+      return;
+    }
+
+    const token: OperationToken = {};
+    const active = this.operations.beginGlobal(token);
+    if (active !== undefined) {
+      await vscode.window.showWarningMessage(t("An mcpp operation is already running."), warningLabels.showTasks);
+      return;
+    }
+
+    try {
+      const args = mcppCommandArguments("toolchain", "default", picked.spec);
+      const result = await runProcess(
+        this.mcppExecutable(project),
+        args,
+        workingDirectory(project),
+      );
+      this.appendShortCommand(t("Set the global default toolchain"), this.mcppExecutable(project), args, result);
+      if (result.exitCode !== 0) {
+        this.reportCommandFailure(
+          args,
+          result.exitCode,
+          `${result.stdout}\n${result.stderr}`,
+          t("Setting the global default toolchain failed (exit code {0}). See the mcpp output channel.", result.exitCode),
+        );
+        return;
+      }
+
+    } finally {
+      this.operations.finishGlobal(token);
+    }
+
+    const buildChoice = await vscode.window.showInformationMessage(
+      t("The mcpp global default is now {0} + host target. Cleaning the old toolchain artifacts and rebuilding is recommended.", picked.spec),
+      ...(project === undefined ? [] : [warningLabels.cleanAndBuild]),
+    );
+    if (buildChoice === warningLabels.cleanAndBuild && project !== undefined) {
+      const cleanArgs = mcppCommandArguments("clean");
+      const cleanResult = await runProcess(this.mcppExecutable(project), cleanArgs, project.root);
+      this.appendShortCommand(t("Clean old artifacts"), this.mcppExecutable(project), cleanArgs, cleanResult);
+      await this.runProjectTask("build");
+    }
+  }
+
+  private async pickInstallSpec(inventory: ToolchainInventory | undefined): Promise {
+    const labels = controllerLabels();
+    const items: ToolchainPickItem[] = [];
+    for (const toolchain of inventory?.available ?? []) {
+      items.push({
+        label: toolchain.spec,
+        description: t("Versions mcpp aggregates by family; this operation installs for the host target"),
+        spec: toolchain.spec,
+      });
+    }
+    items.push({
+      label: labels.installCustom,
+      detail: t("Accepts family, family@version, namespace, partial versions and mcpp's compatible legacy spellings"),
+      customInput: true,
+    });
+
+    const picked = await vscode.window.showQuickPick(items, {
+      title: t("Install an mcpp toolchain"),
+      placeHolder: t("No target is selected; for a target-specific install use the mcpp CLI"),
+      matchOnDescription: true,
+      matchOnDetail: true,
+    });
+    if (picked === undefined) {
+      return undefined;
+    }
+    if (!picked.customInput) {
+      return picked.spec;
+    }
+
+    const input = await vscode.window.showInputBox({
+      title: t("Enter a toolchain spec"),
+      prompt: t("For example gcc, llvm@20.1.7, xim:gcc@16, msvc, mingw; mcpp normalises compatible spellings"),
+      placeHolder: "gcc@16",
+      validateInput: (value) => {
+        const normalized = normalizeToolchainSpec(value);
+        if (normalized === undefined) {
+          return t("Enter a family, family@version, family version, namespace or an mcpp-compatible spec");
+        }
+        return undefined;
+      },
+    });
+    return input === undefined ? undefined : normalizeToolchainSpec(input);
+  }
+
+  private inventoryItems(
+    inventory: ToolchainInventory,
+    includeActions: boolean,
+    project: McppProjectDiscovery | undefined,
+  ): ToolchainPickItem[] {
+    const items: ToolchainPickItem[] = [];
+    const nestedView = this.isNestedWorkspaceProject(project);
+    if (inventory.effective !== undefined) {
+      items.push({
+        label: `$(check) ${nestedView ? t("mcpp list toolchain for this directory") : t("Current effective toolchain")}: ${inventory.effective.spec}`,
+        description: nestedView
+          ? t("This is the current-directory view; the value mcpp build resolves is authoritative")
+          : inventory.projectOverridesGlobal ? t("From this project's mcpp.toml, overriding the global default") : t("From the global default"),
+        detail: inventory.effectiveTarget === undefined
+          ? t("Effective target: host (mcpp shows no explicit target)")
+          : t("Effective target: {0}", inventory.effectiveTarget),
+      });
+    }
+    if (inventory.globalDefaultSpec !== undefined) {
+      items.push({
+        label: t("Global default: {0}", inventory.globalDefaultSpec),
+        description: nestedView
+          ? t("This is the current-directory view; overrides from the project or a parent configuration are decided by the actual build")
+          : inventory.projectOverridesGlobal ? t("This project may not be using this value") : t("mcpp global configuration"),
+      });
+    } else if (inventory.recognized) {
+      items.push({
+        label: t("Global default: "),
+        description: t("mcpp has no global default toolchain yet"),
+      });
+    }
+    for (const toolchain of inventory.installed) {
+      items.push({
+        label: `${toolchain.effective ? "$(check) " : ""}${toolchain.spec}`,
+        description: toolchain.source === "system" ? t("System: system toolchain, detection only") : t("Installed"),
+        detail: toolchain.effective
+          ? nestedView ? t("mcpp list item effective for this directory; the actual build resolution may be affected by a parent mcpp workspace") : t("Currently effective item")
+          : undefined,
+        spec: toolchain.spec,
+        toolchain,
+      });
+    }
+    for (const target of inventory.targets) {
+      items.push({
+        label: `${target.effective ? "$(check) " : ""}target ${target.target}`,
+        description: `${target.status}${target.toolchainSpec === undefined ? "" : ` · ${t("convention {0}", target.toolchainSpec)}`}`,
+        detail: target.note.length === 0 ? t("The target axis is shown read-only; to select a target use the mcpp CLI") : target.note,
+      });
+    }
+    for (const toolchain of inventory.available) {
+      items.push({
+        label: t("Installable: {0}", toolchain.spec),
+        description: t("Index versions mcpp aggregates by family; no host payload is promised"),
+        spec: toolchain.spec,
+      });
+    }
+    if (includeActions) {
+      items.push({
+        label: t("$(cloud-download) Install a toolchain…"),
+        detail: t("Back to the toolchain installation flow"),
+        customInput: true,
+      });
+    }
+    return items;
+  }
+
+  /**
+   * The status bar menu: one section per group, one row per command.
+   *
+   * The section titles come from `QUICK_MENU_GROUPS`, so an entry can never be
+   * filed under a heading that does not exist, and the headers are only emitted
+   * where the entries actually change group — a group whose commands are all
+   * filtered out (C++ Modules, when `mcpp.languageService.menuItems` is off)
+   * takes its heading with it.
+   *
+   * The icons are the generated ones under `media/quick-menu/`, handed over as a
+   * `{ light, dark }` pair so the row is legible in both themes. They cannot be
+   * `ThemeIcon`s: VS Code drops a `ThemeIcon`'s colour in a quick pick and paints
+   * a `Uri` as an image, so a coloured row needs a coloured file. See the note at
+   * the top of `src/commands/menu.ts`.
+   *
+   * Typing filters by command name only. The group names are separator rows, and
+   * VS Code hides separators as soon as a query is present, so they are not
+   * matchable — the headings are for reading the list, not for searching it.
+   */
+  private async showMenu(): Promise {
+    const groupLabel = new Map(QUICK_MENU_GROUPS.map((group) => [group.id, t(group.labelKey)]));
+    const showLanguageServer = read("mcpp.languageService.menuItems");
+    const items: Array = [];
+    let section: string | undefined;
+    for (const item of quickMenuItems) {
+      if (!showLanguageServer && item.group === "languageServer") {
+        continue;
+      }
+      if (item.group !== section) {
+        section = item.group;
+        items.push({
+          label: groupLabel.get(item.group) ?? item.group,
+          kind: vscode.QuickPickItemKind.Separator,
+        });
+      }
+      items.push({
+        label: t(item.labelKey),
+        iconPath: {
+          light: vscode.Uri.joinPath(this.options.extensionUri, QUICK_MENU_ICON_DIRECTORY, quickMenuIconAsset(item, "light")),
+          dark: vscode.Uri.joinPath(this.options.extensionUri, QUICK_MENU_ICON_DIRECTORY, quickMenuIconAsset(item, "dark")),
+        },
+        command: item.command,
+      });
+    }
+    const picked = await vscode.window.showQuickPick(items, {
+      title: t("mcpp: quick menu"),
+      placeHolder: t("Choose a project, toolchain, cache or C++ Modules action"),
+    });
+    if (picked?.command !== undefined) {
+      await vscode.commands.executeCommand(picked.command);
+    }
+  }
+
+  public async newProject(): Promise {
+    if (!this.requireTrusted()) {
+      return;
+    }
+
+    const input = await vscode.window.showInputBox({
+      title: t("New mcpp project (1/2)"),
+      prompt: t("Enter a project name; a folder of that name is created at the location you pick"),
+      placeHolder: "hello-mcpp",
+      validateInput: validateNewProjectName,
+    });
+    if (input === undefined) {
+      return;
+    }
+    const projectName = input.trim();
+
+    const picked = await vscode.window.showOpenDialog({
+      title: t("Choose the project location (2/2)"),
+      // Start where the reader already is: `mcpp new` creates a folder *inside*
+      // the chosen one, so the workspace folder is the useful default — the
+      // project itself cannot be created in it, because `mcpp new` refuses a
+      // destination that already exists.
+      defaultUri: vscode.workspace.workspaceFolders?.[0]?.uri,
+      canSelectFiles: false,
+      canSelectFolders: true,
+      canSelectMany: false,
+      openLabel: t("Create the project here"),
+    });
+    const location = picked?.[0];
+    if (location === undefined) {
+      return;
+    }
+
+    const projectRoot = join(location.fsPath, projectName);
+    // Shown *and* compared: one definition keeps the two in step.
+    const confirmCreate = t("Create and open");
+    await runNewProjectFlow(projectName, location.fsPath, projectRoot, {
+      exists: existsSync,
+      confirm: async (message) =>
+        (await vscode.window.showWarningMessage(message, { modal: true }, confirmCreate))
+        === confirmCreate,
+      run: async (name, cwd) => {
+        const executable = this.mcppExecutable(undefined);
+        const args = mcppCommandArguments("new", name);
+        const result = await runProcess(executable, args, cwd);
+        this.appendShortCommand(t("New project"), executable, args, result);
+        return result.exitCode;
+      },
+      openFolder: async (path) => {
+        await vscode.commands.executeCommand("vscode.openFolder", vscode.Uri.file(path));
+      },
+      showError: async (message) => {
+        await vscode.window.showErrorMessage(message);
+      },
+    });
+  }
+
+  private guarded(operation: () => Promise): () => Promise {
+    return async () => {
+      try {
+        await operation();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.logger.error(t("mcpp CLI operation failed: {0}", message));
+        await vscode.window.showErrorMessage(t("mcpp: {0}", message));
+      }
+    };
+  }
+
+  private requireProject(): McppProjectDiscovery | undefined {
+    const project = this.options.currentProject();
+    if (project === undefined) {
+      void vscode.window.showWarningMessage(t("No mcpp.toml was found in this workspace. Run this command inside an mcpp project."));
+    }
+    return project;
+  }
+
+  private requireTrusted(): boolean {
+    if (this.options.isTrusted()) {
+      return true;
+    }
+    void vscode.window.showWarningMessage(
+      t("This workspace is not trusted. mcpp commands may run external programs named by workspace settings; trust the workspace first."),
+    );
+    return false;
+  }
+
+  public mcppExecutable(project: McppProjectDiscovery | undefined): string {
+    const uri = project === undefined
+      ? vscode.workspace.workspaceFolders?.[0]?.uri
+      : vscode.Uri.file(project.root);
+    const configured = vscode.workspace.getConfiguration("mcpp", uri).get("path", "").trim();
+    return configured.length === 0 ? "mcpp" : configured;
+  }
+
+  private isNestedWorkspaceProject(project: McppProjectDiscovery | undefined): boolean {
+    if (project === undefined) {
+      return false;
+    }
+    const folder = vscode.workspace.getWorkspaceFolder(vscode.Uri.file(project.root));
+    return folder !== undefined && folder.uri.fsPath !== project.root;
+  }
+
+  public async readToolchainInventory(
+    project: McppProjectDiscovery | undefined = this.options.currentProject(),
+  ): Promise {
+    const executable = this.mcppExecutable(project);
+    const args = mcppCommandArguments("toolchain", "list");
+    const result = await runProcess(executable, args, workingDirectory(project));
+    this.appendShortCommand(t("Inspect the toolchain"), executable, args, result);
+    if (result.exitCode !== 0) {
+      this.reportCommandFailure(
+        args,
+        result.exitCode,
+        `${result.stdout}\n${result.stderr}`,
+        t("mcpp toolchain list failed (exit code {0}). See the mcpp output channel.", result.exitCode),
+      );
+      return undefined;
+    }
+
+    const inventory = parseToolchainList(`${result.stdout}${result.stderr.length > 0 ? `\n${result.stderr}` : ""}`);
+    if (!inventory.recognized) {
+      await vscode.window.showErrorMessage(
+        t("The current mcpp toolchain list output is not recognised; the raw output is kept in the mcpp output channel, so check the mcpp version."),
+      );
+      return undefined;
+    }
+    return inventory;
+  }
+
+  private async executeTask(
+    root: string,
+    executable: string,
+    title: string,
+    args: string[],
+  ): Promise {
+    // `mcpp.task.revealTerminal` / `focusTerminal` / `clearTerminal` and
+    // `mcpp.task.problemMatcher` are read here, where the task object is
+    // assembled; the completion path re-reads them for the failure-only reveal.
+    const ui = this.terminalUi(root);
+    const task = new vscode.Task(
+      { type: "mcpp", command: args[0] ?? "mcpp", projectRoot: root },
+      taskScope(root),
+      title,
+      "mcpp",
+      new vscode.ProcessExecution(executable, args, { cwd: root }),
+      [...problemMatchersFor(read("mcpp.task.problemMatcher", vscode.Uri.file(root)))],
+    );
+    task.presentationOptions = {
+      reveal: ui.reveal === "always"
+        ? vscode.TaskRevealKind.Always
+        : ui.reveal === "never"
+          ? vscode.TaskRevealKind.Never
+          : vscode.TaskRevealKind.Silent,
+      panel: vscode.TaskPanelKind.Dedicated,
+      focus: ui.focus,
+      clear: ui.clearBeforeRun,
+      showReuseMessage: false,
+    };
+
+    let execution: vscode.TaskExecution | undefined;
+    let earlyCompletion: TaskCompletion | undefined;
+    let settled = false;
+    let processEndSubscription: vscode.Disposable | undefined;
+    let taskEndSubscription: vscode.Disposable | undefined;
+    const disposeListeners = (): void => {
+      processEndSubscription?.dispose();
+      taskEndSubscription?.dispose();
+    };
+    const finish = (completion: TaskCompletion): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      disposeListeners();
+      resolveCompletion?.(completion);
+    };
+    let resolveCompletion: ((completion: TaskCompletion) => void) | undefined;
+    const completion = new Promise((resolve) => {
+      resolveCompletion = resolve;
+      processEndSubscription = vscode.tasks.onDidEndTaskProcess((event) => {
+        if (event.execution.task !== task) {
+          return;
+        }
+        const classified = classifyTaskExit(event.exitCode);
+        if (execution === undefined) {
+          earlyCompletion ??= classified;
+          return;
+        }
+        finish(classified);
+      });
+      taskEndSubscription = vscode.tasks.onDidEndTask((event) => {
+        if (event.execution.task !== task) {
+          return;
+        }
+        const classified = classifyTaskExit(undefined);
+        if (execution === undefined) {
+          earlyCompletion ??= classified;
+          return;
+        }
+        finish(classified);
+      });
+    });
+
+    try {
+      execution = await vscode.tasks.executeTask(task);
+    } catch (error) {
+      disposeListeners();
+      throw error;
+    }
+    if (earlyCompletion !== undefined) {
+      finish(earlyCompletion);
+    }
+    return completion;
+  }
+
+  private appendTaskCompletion(
+    root: string,
+    title: string,
+    args: string[],
+    completion: TaskCompletion,
+  ): void {
+    const suffix = completion.state === "succeeded"
+      ? t("Exit code {0}", completion.exitCode ?? 0)
+      : completion.state === "cancelled"
+        ? t("Cancelled")
+        : t("Failed with exit code {0}", completion.exitCode ?? t("unknown"));
+    // `mcpp.log.level` gates the verbose lines; the failed result is an error
+    // and is therefore never suppressed.
+    this.logger.info(`\n[${new Date().toISOString()}] ${title}`);
+    this.logger.debug(t("Working directory: {0}", root));
+    this.logger.debug(t("Task arguments: {0}", args.join(" ")));
+    const resultLine = t("Result: {0}", suffix);
+    if (completion.state === "failed") {
+      this.logger.error(resultLine);
+    } else if (completion.state === "cancelled") {
+      this.logger.warn(resultLine);
+    } else {
+      this.logger.info(resultLine);
+    }
+
+    for (const command of terminalCommandsAfterTask(this.terminalUi(root), completion.state === "failed")) {
+      void vscode.commands.executeCommand(command);
+    }
+
+    if (completion.state === "failed") {
+      this.reportCommandFailure(
+        args,
+        completion.exitCode ?? 1,
+        "",
+        t("{0} failed (exit code {1}). See the task terminal.", title, completion.exitCode ?? t("unknown")),
+      );
+    } else if (completion.state === "cancelled") {
+      void vscode.window.showWarningMessage(t("{0} was cancelled.", title));
+    } else {
+      this.reportSuccess(t("{0} finished.", title));
+    }
+  }
+
+  /** The task-terminal settings, read together so every site agrees. */
+  private terminalUi(root: string): TaskTerminalUi {
+    const resource = vscode.Uri.file(root);
+    return taskTerminalUi(
+      read("mcpp.task.revealTerminal", resource),
+      read("mcpp.task.focusTerminal", resource),
+      read("mcpp.task.clearTerminal", resource),
+    );
+  }
+
+  /**
+   * A *successful* result only; failures and cancellations never consult
+   * `mcpp.ui.notifications.success`. `mcpp.ui.notifications.dedupeMinutes`
+   * suppresses a repeated identical message inside its window.
+   */
+  private reportSuccess(message: string): void {
+    const mode = successReportOf(read("mcpp.ui.notifications.success"));
+    if (mode === "silent") {
+      return;
+    }
+    const now = Date.now();
+    if (!dedupeAllows(this.lastNotified.get(message), now, read("mcpp.ui.notifications.dedupeMinutes"))) {
+      return;
+    }
+    this.lastNotified.set(message, now);
+    if (mode === "toast") {
+      void vscode.window.showInformationMessage(message);
+      return;
+    }
+    this.showStatusSuccess(message);
+  }
+
+  /** `mcpp.ui.notifications.success = statusBar`: a transient, non-blocking label. */
+  private showStatusSuccess(message: string): void {
+    if (this.options.currentProject() === undefined || !read("mcpp.ui.statusBar.show")) {
+      return;
+    }
+    this.status.text = `$(check) ${statusBarSuccessText(message)}`;
+    this.status.show();
+    if (this.statusRevert !== undefined) {
+      clearTimeout(this.statusRevert);
+    }
+    this.statusRevert = setTimeout(() => {
+      this.statusRevert = undefined;
+      try {
+        this.applyStatusBar();
+      } catch {
+        // The status item can already be disposed during a window reload.
+      }
+    }, SUCCESS_STATUS_MS);
+  }
+
+  /**
+   * A failed `mcpp` run: the exit-code-specific next step from
+   * `src/cli/errors.ts`, the caller's own message as the fallback, and the
+   * `mcpp self explain` hint whenever the output names a diagnostic code.
+   */
+  private reportCommandFailure(
+    args: readonly string[],
+    exitCode: number,
+    output: string,
+    fallback: string,
+  ): void {
+    const advice = failureAdvice(args, exitCode, output);
+    const parts: string[] = [failureGuidanceText(advice.kind) ?? fallback];
+    if (advice.hint !== undefined) {
+      parts.push(t("Explain this code with: {0}", advice.hint));
+    }
+    void vscode.window.showErrorMessage(parts.join(" "));
+  }
+
+  private warningOptions(strength: ConfirmationStrength, detail: string): vscode.MessageOptions {
+    return strength === "modal" ? { modal: true, detail } : { detail };
+  }
+
+  /**
+   * `mcpp.ui.statusBar.show` plus `mcpp.ui.statusBar.showLanguageServer`; the
+   * C++ Modules line comes from the host callback, so this controller never
+   * imports the mcppls bridge.
+   */
+  private applyStatusBar(): void {
+    if (this.statusRevert !== undefined) {
+      clearTimeout(this.statusRevert);
+      this.statusRevert = undefined;
+    }
+    const tooltip = t("Open the mcpp project and toolchain quick menu");
+    const languageServer = languageServerStatusSuffix(
+      read("mcpp.ui.statusBar.showLanguageServer"),
+      this.options.languageServerSummary?.(),
+    );
+    this.status.text = languageServer === undefined
+      ? quickMenuStatusText
+      : `${quickMenuStatusText} · ${t("C++ Modules: {0}", languageServer)}`;
+    this.status.tooltip = languageServer === undefined
+      ? tooltip
+      : `${tooltip}\n${t("C++ Modules (provided by the mcpp language server extension): {0}", languageServer)}`;
+    // `mcpp.ui.statusBar.background`: VS Code allows a status bar entry exactly
+    // two backgrounds and picks the matching foreground itself; see
+    // `src/cli/statusBar.ts` for the whitelist this reads.
+    const background = statusBarBackgroundColour(read("mcpp.ui.statusBar.background"));
+    this.status.backgroundColor = background === undefined ? undefined : new vscode.ThemeColor(background);
+    if (read("mcpp.ui.statusBar.show")) {
+      this.status.show();
+    } else {
+      this.status.hide();
+    }
+  }
+
+  private appendShortCommand(
+    title: string,
+    executable: string,
+    args: string[],
+    result: { exitCode: number; stdout: string; stderr: string },
+  ): void {
+    // The command echo and the output of a successful command are the verbose
+    // lines `mcpp.log.level` gates. A failed command's raw stdout/stderr is
+    // written at `error`, which no configured level may suppress.
+    const failed = result.exitCode !== 0;
+    this.logger.info(`\n[${new Date().toISOString()}] ${title}`);
+    this.logger.debug(`$ ${commandLine(executable, args)}`);
+    if (result.stdout.length > 0) {
+      (failed ? this.logger.error : this.logger.info)(result.stdout.trimEnd());
+    }
+    if (result.stderr.length > 0) {
+      (failed ? this.logger.error : this.logger.info)(result.stderr.trimEnd());
+    }
+    (failed ? this.logger.error : this.logger.info)(`[exit ${result.exitCode}]`);
+  }
+}
diff --git a/src/cli/errors.ts b/src/cli/errors.ts
new file mode 100644
index 0000000..a24fc35
--- /dev/null
+++ b/src/cli/errors.ts
@@ -0,0 +1,156 @@
+/**
+ * mcpp's exit-code contract (SPEC-003) turned into something a UI can branch on.
+ *
+ * | code | meaning                                    |
+ * |------|--------------------------------------------|
+ * | 0    | success                                    |
+ * | 1    | ran and failed                             |
+ * | 2    | usage error                                |
+ * | 4    | environment not ready                      |
+ * | 70   | internal error                             |
+ * | 101  | build failure — **only for `mcpp run`**    |
+ * | 127  | unknown command                            |
+ *
+ * Two documented quirks are respected by the callers of this module:
+ * `mcpp build --configure-only` returns **2** for a *planning* failure, and
+ * `mcpp emit build-database` returns **1** together with a usable envelope —
+ * see {@link hasUsableOutput}. Nothing here parses narration for meaning; the
+ * only text it understands is the `MCPP_*` diagnostic code that
+ * `mcpp self explain` accepts.
+ *
+ * Pure string/number functions: no child process, no `vscode`.
+ */
+
+export type McppFailureKind =
+  | "none"
+  | "failed"
+  | "usage"
+  | "environment"
+  | "internal"
+  | "build-failed"
+  | "unknown-command"
+  | "cancelled";
+
+export interface McppOutcome {
+  kind: McppFailureKind;
+  /** Raw exit code, or -1 when the process could not be started at all. */
+  exitCode: number;
+  /** The single stderr line that best explains it, when there is one. */
+  detail?: string;
+  /** A `MCPP_*` diagnostic code found in the output, when there is one. */
+  diagnosticCode?: string;
+}
+
+const USAGE = 2;
+const ENVIRONMENT = 4;
+const INTERNAL = 70;
+const BUILD_FAILED = 101;
+const UNKNOWN_COMMAND = 127;
+
+/** `MCPP_OFFLINE_DOWNLOAD_REQUIRED`, never a lowercase word like `mcpp_offline`. */
+const DIAGNOSTIC_CODE = /\bMCPP_[A-Z][A-Z0-9_]*/;
+
+/**
+ * Map an exit code (plus the argv that produced it, which is the only way to
+ * tell `mcpp run`'s build failure apart) to a failure kind.
+ *
+ * `undefined` means "the process never produced an exit code" — a spawn failure
+ * or a cancellation — and yields `{ kind: "cancelled", exitCode: -1 }`. Signal
+ * terminations reported as a negative code are treated the same way.
+ *
+ * Codes that are not in the contract (for example a program's own exit code
+ * relayed by `mcpp run`) fall back to `"failed"`.
+ */
+export function classifyExit(exitCode: number | undefined, command?: readonly string[]): McppOutcome {
+  if (typeof exitCode !== "number" || !Number.isFinite(exitCode) || exitCode < 0) {
+    return { kind: "cancelled", exitCode: -1 };
+  }
+  if (exitCode === 0) {
+    return { kind: "none", exitCode };
+  }
+  if (exitCode === UNKNOWN_COMMAND) {
+    return { kind: "unknown-command", exitCode };
+  }
+  if (exitCode === BUILD_FAILED) {
+    // 101 is `mcpp run`'s "your program failed to build"; for anything else it
+    // is an ordinary runtime failure.
+    return { kind: command?.[0] === "run" ? "build-failed" : "failed", exitCode };
+  }
+  if (exitCode === USAGE) {
+    return { kind: "usage", exitCode };
+  }
+  if (exitCode === ENVIRONMENT) {
+    return { kind: "environment", exitCode };
+  }
+  if (exitCode === INTERNAL) {
+    return { kind: "internal", exitCode };
+  }
+  return { kind: "failed", exitCode };
+}
+
+/** The first `MCPP_*` diagnostic code in `output`, when there is one. */
+export function diagnosticCodeIn(output: string): string | undefined {
+  if (typeof output !== "string") {
+    return undefined;
+  }
+  return DIAGNOSTIC_CODE.exec(output)?.[0];
+}
+
+/** Minimal JSON extraction for salvage checks: the trimmed text, then its outermost `{…}` / `[…]`. */
+function jsonDocumentIn(stdout: string): unknown {
+  if (typeof stdout !== "string") {
+    return undefined;
+  }
+  const text = stdout.trim();
+  if (text.length === 0) {
+    return undefined;
+  }
+  const attempts = [text];
+  const objectStart = text.indexOf("{");
+  const objectEnd = text.lastIndexOf("}");
+  if (objectStart >= 0 && objectEnd > objectStart) {
+    attempts.push(text.slice(objectStart, objectEnd + 1));
+  }
+  const arrayStart = text.indexOf("[");
+  const arrayEnd = text.lastIndexOf("]");
+  if (arrayStart >= 0 && arrayEnd > arrayStart) {
+    attempts.push(text.slice(arrayStart, arrayEnd + 1));
+  }
+  for (const attempt of attempts) {
+    try {
+      const parsed: unknown = JSON.parse(attempt);
+      if (typeof parsed === "object" && parsed !== null) {
+        return parsed;
+      }
+    } catch {
+      // Not this candidate; try the next one.
+    }
+  }
+  return undefined;
+}
+
+/**
+ * True when stdout carried something usable **even though the exit code was
+ * non-zero** — the `mcpp emit build-database` partial-failure case, where the
+ * envelope and its `diagnostics` are still worth reading.
+ *
+ * False when the command succeeded (there is nothing to salvage) and false when
+ * stdout has no parseable JSON document. A bare `--json` document counts just
+ * like an envelope.
+ */
+export function hasUsableOutput(outcome: McppOutcome, stdout: string): boolean {
+  if (outcome.exitCode === 0) {
+    return false;
+  }
+  return jsonDocumentIn(stdout) !== undefined;
+}
+
+/**
+ * The follow-up command that explains a failure, e.g.
+ * `mcpp self explain MCPP_OFFLINE_DOWNLOAD_REQUIRED`. `undefined` when there is
+ * no diagnostic code to explain.
+ */
+export function explainHint(outcome: McppOutcome): string | undefined {
+  const code = outcome.diagnosticCode ?? diagnosticCodeIn(outcome.detail ?? "");
+  return code === undefined ? undefined : `mcpp self explain ${code}`;
+}
diff --git a/src/cli/labels.ts b/src/cli/labels.ts
new file mode 100644
index 0000000..96a4757
--- /dev/null
+++ b/src/cli/labels.ts
@@ -0,0 +1,43 @@
+/**
+ * The controller's own buttons.
+ *
+ * `showWarningMessage` / `showInformationMessage` reply with the label the user
+ * pressed, so a button that is both **displayed** and **compared** must be
+ * defined exactly once: two literals would silently desynchronise, and the
+ * comparison would never match a translated label.
+ *
+ * Kept out of `controller.ts` so it stays importable without an editor (`t()`
+ * loads the editor API lazily) and `test/cli/labels.test.ts` can hold the
+ * identity rule.
+ */
+
+import { t } from "../i18n/t";
+
+export interface ControllerLabels {
+  installCustom: string;
+  confirmInstall: string;
+  confirmDetect: string;
+  confirmDefault: string;
+  confirmClean: string;
+  chooseGlobalDefault: string;
+  cleanAndBuild: string;
+  showTasks: string;
+}
+
+/**
+ * Resolved on every call, so `mcpp.ui.language` applies without a reload, and
+ * read once per dialogue into a local `labels` value that serves both the
+ * prompt and the `===` comparison.
+ */
+export function controllerLabels(): ControllerLabels {
+  return {
+    installCustom: t("$(edit) Enter another compatible toolchain spec…"),
+    confirmInstall: t("Install"),
+    confirmDetect: t("Detect"),
+    confirmDefault: t("Set as global default"),
+    confirmClean: t("Clean target"),
+    chooseGlobalDefault: t("Choose a global default"),
+    cleanAndBuild: t("Clean and build"),
+    showTasks: t("Show running tasks"),
+  };
+}
diff --git a/src/newProject.ts b/src/cli/newProject.ts
similarity index 70%
rename from src/newProject.ts
rename to src/cli/newProject.ts
index e7b6f0c..90547e6 100644
--- a/src/newProject.ts
+++ b/src/cli/newProject.ts
@@ -1,3 +1,5 @@
+import { t } from "../i18n/t";
+
 export interface NewProjectActions {
   exists(path: string): boolean;
   confirm(message: string): Promise;
@@ -20,11 +22,11 @@ export async function runNewProjectFlow(
   actions: NewProjectActions,
 ): Promise {
   if (actions.exists(projectRoot)) {
-    await actions.showError(`目标路径已存在：${projectRoot}。请更换项目名或位置。`);
+    await actions.showError(t("The destination already exists: {0}. Choose another project name or location.", projectRoot));
     return "exists";
   }
   const confirmed = await actions.confirm(
-    `将在 ${location} 执行 “mcpp new ${projectName}”，创建项目文件夹 ${projectRoot} 并打开它。`,
+    t("Run “mcpp new {0}” in {1}, create the project folder {2} and open it.", projectName, location, projectRoot),
   );
   if (!confirmed) {
     return "declined";
@@ -32,7 +34,7 @@ export async function runNewProjectFlow(
   const exitCode = await actions.run(projectName, location);
   if (exitCode !== 0) {
     await actions.showError(
-      `mcpp new ${projectName} 失败（退出码 ${exitCode}）。请查看 mcpp 输出频道。`,
+      t("mcpp new {0} failed (exit code {1}). See the mcpp output channel.", projectName, exitCode),
     );
     return "failed";
   }
@@ -59,32 +61,32 @@ const MCPP_BUILTIN_TEMPLATE_MARKER = "PROJECT";
 export function validateNewProjectName(input: string): string | undefined {
   const name = input.trim();
   if (name.length === 0) {
-    return "项目名不能为空";
+    return t("The project name must not be empty.");
   }
   if (/[\\/]/.test(name)) {
-    return "项目名不能包含路径分隔符";
+    return t("The project name must not contain a path separator.");
   }
   if (name.startsWith("-")) {
-    return "项目名不能以 - 开头，否则会被 mcpp 解析为命令行选项";
+    return t("The project name must not start with -, or mcpp would read it as a command-line option.");
   }
   if (name === "." || name === "..") {
-    return "项目名不能是 . 或 ..";
+    return t("The project name must not be . or ..");
   }
   // mcpp#380：当前内置模板会重复扫描替换结果，名称包含该标记时不会终止。
   if (name.includes(MCPP_BUILTIN_TEMPLATE_MARKER)) {
-    return "项目名不能包含 PROJECT，否则会触发当前 mcpp 模板替换缺陷";
+    return t("The project name must not contain PROJECT: it triggers a defect in the current mcpp template substitution.");
   }
   if (CONTROL_CHARS.test(name)) {
-    return "项目名不能包含控制字符";
+    return t("The project name must not contain control characters.");
   }
   if (WINDOWS_RESERVED_CHARS.test(name)) {
-    return '项目名不能包含 <>:"|?* 等保留字符';
+    return t('The project name must not contain reserved characters such as <>:"|?*.');
   }
   if (name.endsWith(".")) {
-    return "项目名不能以 . 结尾（Windows 不支持）";
+    return t("The project name must not end with . (unsupported on Windows).");
   }
   if (WINDOWS_DEVICE_NAMES.test(name)) {
-    return "项目名不能是 Windows 保留设备名";
+    return t("The project name must not be a Windows reserved device name.");
   }
   return undefined;
 }
diff --git a/src/cli/process.ts b/src/cli/process.ts
new file mode 100644
index 0000000..a0c58a8
--- /dev/null
+++ b/src/cli/process.ts
@@ -0,0 +1,120 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface ProcessResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface ProcessRunOptions {
+  timeoutMs?: number;
+  /** `mcpp.runtime.maxOutputMiB`; the default matches what the extension shipped before it was configurable. */
+  maxBufferMiB?: number;
+}
+
+export type ProcessRunner = (
+  executable: string,
+  args: string[],
+  cwd?: string,
+  options?: ProcessRunOptions,
+) => Promise;
+
+/**
+ * Windows cannot `execFile` a `.cmd`/`.bat` shim directly — Node ≥ 20.12 rejects
+ * it with EINVAL outright, and older hosts still mis-handle shebang scripts. A
+ * `mcpp.path` that points at such a wrapper (npm-style shim, the e2e fake mcpp)
+ * therefore has to go through the shell. Everywhere else the direct spawn is
+ * both safer and faster, so only these two suffixes opt in.
+ */
+export function spawnNeedsShell(executable: string, platform: NodeJS.Platform = process.platform): boolean {
+  return platform === "win32" && /\.(cmd|bat)$/i.test(executable);
+}
+
+/**
+ * One argument, quoted for the shell path (external review P1-2, 2026-10-03).
+ *
+ * Node joins `file` and `args` with plain spaces when `shell: true`, without
+ * quoting anything, so a path with a space (`C:\Users\John Doe\…`, exactly what
+ * `xpkg parse` receives) splits in two and a search term like `foo & calc`
+ * becomes two commands. The rule is the one `CommandLineToArgvW` applies when
+ * the target re-parses the line: double backslashes that precede a quote or end
+ * the argument, escape the quotes themselves, and wrap in double quotes —
+ * inside which cmd treats `& | < > ^` as literal. `%VAR%` expansion inside
+ * quotes is a cmd limitation every shell-spawner shares and stays documented
+ * here rather than half-fixed.
+ */
+export function quoteWindowsArgument(argument: string): string {
+  let quoted = argument.replace(/(\\*)"/g, '$1$1\\"');
+  quoted = quoted.replace(/(\\*)$/, '$1$1');
+  return `"${quoted}"`;
+}
+
+export async function runProcess(
+  executable: string,
+  args: string[],
+  cwd?: string,
+  options: ProcessRunOptions = {},
+): Promise {
+  try {
+    const needsShell = spawnNeedsShell(executable);
+    const result = await execFileAsync(
+      needsShell ? quoteWindowsArgument(executable) : executable,
+      needsShell ? args.map(quoteWindowsArgument) : args,
+      {
+        cwd,
+        encoding: "utf8",
+        maxBuffer: Math.max(1, options.maxBufferMiB ?? 16) * 1024 * 1024,
+        timeout: options.timeoutMs,
+        ...(needsShell ? { shell: true } : {}),
+      },
+    );
+    return {
+      exitCode: 0,
+      stdout: result.stdout,
+      stderr: result.stderr,
+    };
+  } catch (error) {
+    const processError = error as NodeJS.ErrnoException & {
+      stdout?: string;
+      stderr?: string;
+      code?: number | string;
+    };
+    return {
+      exitCode: typeof processError.code === "number" ? processError.code : 1,
+      stdout: processError.stdout ?? "",
+      stderr: processError.stderr ?? (typeof processError.message === "string" ? processError.message : ""),
+    };
+  }
+}
+
+/**
+ * The one way the extension body runs mcpp: `runProcess` plus the
+ * workspace-trust gate (external review P0, 2026-10-03).
+ *
+ * `mcpp.path` is a `resource`-scoped setting, so an untrusted workspace can
+ * name any program there; every caller outside `src/cli/` therefore goes
+ * through this seam and receives `undefined` — a refusal, not an error — when
+ * the workspace is not trusted. The callers degrade (the detail page falls
+ * back to the descriptor's own text, the cross-registry search keeps its
+ * local results, the self-check reports the probe as unknown) instead of
+ * running the command.
+ *
+ * `src/cli/controller.ts` wraps its own `requireTrusted()` prompts around
+ * whole commands, which is why `src/cli/` may still call `runProcess`
+ * directly; the architecture test holds everyone else to this seam.
+ */
+export async function runMcpp(
+  trusted: boolean,
+  executable: string,
+  args: readonly string[],
+  cwd?: string,
+  options: ProcessRunOptions = {},
+): Promise {
+  if (!trusted) {
+    return undefined;
+  }
+  return runProcess(executable, [...args], cwd, options);
+}
diff --git a/src/cli/protocol.ts b/src/cli/protocol.ts
new file mode 100644
index 0000000..a84841b
--- /dev/null
+++ b/src/cli/protocol.ts
@@ -0,0 +1,259 @@
+/**
+ * mcpp's machine-output protocol (`docs/50-machine-output.md`).
+ *
+ * **Detection rule**: parse stdout and require `schemaVersion` **and** `kind`.
+ * The exit code is never the signal — an older mcpp answers
+ * `mcpp --protocol-version` with human text on stdout and exit 1, and a
+ * *failing* command can still emit a perfectly good envelope
+ * (`mcpp emit build-database` on partial failure). Everything here is a pure
+ * string function: no child process, no `vscode`.
+ *
+ * `mcpp --protocol-version` prints an envelope with a `mcpp.protocol` kind:
+ *
+ * ```jsonc
+ * { "schemaVersion": 1, "kind": "mcpp.protocol",
+ *   "envelope": { "min": 1, "max": 1 },
+ *   "kinds": { "mcpp.env": 1, "mcpp.toolchain.list": 1 },
+ *   "commands": { "toolchain list": { "effects": ["read"] } },
+ *   "mcpp": { "version": "2026.9.30.2", "protocol": { "min": 1, "max": 1 } } }
+ * ```
+ *
+ * `kinds` is the answer to "which `--format json` commands are safe to use" —
+ * see {@link supportsKind}.
+ */
+
+export interface ProtocolEnvelope {
+  schemaVersion: number;
+  kind: string;
+  kindVersion?: number;
+  data?: T;
+  diagnostics?: ProtocolDiagnostic[];
+  effects?: string[];
+  mcpp?: { version?: string; protocol?: { min?: number; max?: number } };
+}
+
+export interface ProtocolDiagnostic {
+  code: string;
+  severity: "error" | "warning" | "note";
+  source?: string;
+  message: string;
+  path?: string;
+  range?: unknown;
+}
+
+export interface ProtocolInfo {
+  mcppVersion?: string;
+  envelopeMax?: number;
+  kinds: Record;
+  /** command name -> the effects it may have, from `mcpp --protocol-version`. */
+  effects: Record;
+}
+
+const PROTOCOL_KIND = "mcpp.protocol";
+
+/**
+ * Upper bound on the number of substrings we are willing to try when a document
+ * is not pure JSON. Only reached for malformed input, and it keeps the scan
+ * linear-ish on a 16 MiB capture.
+ */
+const MAX_JSON_CANDIDATES = 64;
+
+function asRecord(value: unknown): Record | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record;
+}
+
+function readNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Candidate object substrings for a text that is **not** pure JSON: every `{…}`
+ * span between the brace positions. Narration before or after the document (a
+ * `warning:` line, a blank line, an old-mcpp banner) therefore cannot hide it,
+ * and a stray `}` in trailing narration does not either.
+ */
+function jsonCandidates(text: string): string[] {
+  const candidates: string[] = [];
+
+  const starts: number[] = [];
+  for (let index = text.indexOf("{"); index >= 0; index = text.indexOf("{", index + 1)) {
+    starts.push(index);
+    if (starts.length >= MAX_JSON_CANDIDATES) {
+      break;
+    }
+  }
+  const ends: number[] = [];
+  for (let index = text.lastIndexOf("}"); index >= 0; index = text.lastIndexOf("}", index - 1)) {
+    ends.push(index);
+    if (ends.length >= MAX_JSON_CANDIDATES) {
+      break;
+    }
+  }
+
+  for (const start of starts) {
+    // `ends` is descending: the first entry is the outermost closing brace.
+    for (const end of ends) {
+      if (end <= start) {
+        break;
+      }
+      candidates.push(text.slice(start, end + 1));
+      if (candidates.length >= MAX_JSON_CANDIDATES) {
+        return candidates;
+      }
+    }
+  }
+  return candidates;
+}
+
+/** The first JSON object found in `stdout`; `undefined` for anything else. */
+function parseJsonObject(stdout: string): Record | undefined {
+  const text = stdout.trim();
+  if (text.length === 0) {
+    return undefined;
+  }
+  try {
+    // The trimmed text is one complete JSON value, so it *is* the document.
+    // An array or a scalar is not an envelope, and we must not dig an object
+    // out of it.
+    return asRecord(JSON.parse(text) as unknown);
+  } catch {
+    // Narration around the document: fall through to the outermost object.
+  }
+  for (const candidate of jsonCandidates(text)) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(candidate);
+    } catch {
+      continue;
+    }
+    const record = asRecord(parsed);
+    if (record !== undefined) {
+      return record;
+    }
+  }
+  return undefined;
+}
+
+/** Parse stdout as one enveloped document; `undefined` when it is not one. */
+export function parseEnvelope(stdout: string): ProtocolEnvelope | undefined {
+  if (typeof stdout !== "string") {
+    return undefined;
+  }
+  const record = parseJsonObject(stdout);
+  if (record === undefined) {
+    return undefined;
+  }
+  // Presence *and* type: a string `schemaVersion` is not a document we can trust.
+  if (typeof record.schemaVersion !== "number") {
+    return undefined;
+  }
+  if (typeof record.kind !== "string" || record.kind.length === 0) {
+    return undefined;
+  }
+  return record as unknown as ProtocolEnvelope;
+}
+
+function kindVersionOf(value: unknown): number | undefined {
+  const direct = readNumber(value);
+  if (direct !== undefined) {
+    return direct;
+  }
+  const record = asRecord(value);
+  if (record === undefined) {
+    return undefined;
+  }
+  return readNumber(record.version) ?? readNumber(record.max);
+}
+
+function readKindVersions(source: Record | undefined): Record {
+  const versions: Record = {};
+  if (source === undefined) {
+    return versions;
+  }
+  for (const [kind, value] of Object.entries(source)) {
+    const version = kindVersionOf(value);
+    if (version !== undefined) {
+      versions[kind] = version;
+    }
+  }
+  return versions;
+}
+
+function readCommandEffects(source: Record | undefined): Record {
+  const effects: Record = {};
+  if (source === undefined) {
+    return effects;
+  }
+  for (const [command, value] of Object.entries(source)) {
+    const entry = asRecord(value);
+    if (entry === undefined || !Array.isArray(entry.effects)) {
+      continue;
+    }
+    effects[command] = entry.effects.filter((item): item is string => typeof item === "string");
+  }
+  return effects;
+}
+
+/**
+ * Parse `mcpp --protocol-version`. Returns `undefined` for older mcpp (human
+ * text on stdout, exit 1) and for any document that is not the protocol
+ * envelope, so the caller can fall back to the legacy text path.
+ *
+ * The fields sit at the envelope's top level in the real output; `data` is
+ * accepted as well so a future nesting cannot silently disable the probe.
+ */
+export function parseProtocolInfo(stdout: string): ProtocolInfo | undefined {
+  const envelope = parseEnvelope(stdout) as
+    | (ProtocolEnvelope & Record)
+    | undefined;
+  if (envelope === undefined || envelope.kind !== PROTOCOL_KIND) {
+    return undefined;
+  }
+
+  const data = asRecord(envelope.data);
+  const mcpp = asRecord(envelope.mcpp) ?? asRecord(data?.mcpp);
+  const envelopeRange = asRecord(envelope.envelope) ?? asRecord(data?.envelope);
+  const protocolRange = asRecord(mcpp?.protocol);
+
+  const info: ProtocolInfo = {
+    kinds: readKindVersions(asRecord(envelope.kinds) ?? asRecord(data?.kinds)),
+    effects: readCommandEffects(asRecord(envelope.commands) ?? asRecord(data?.commands)),
+  };
+  const mcppVersion = readString(mcpp?.version);
+  if (mcppVersion !== undefined) {
+    info.mcppVersion = mcppVersion;
+  }
+  const envelopeMax = readNumber(envelopeRange?.max) ?? readNumber(protocolRange?.max);
+  if (envelopeMax !== undefined) {
+    info.envelopeMax = envelopeMax;
+  }
+  return info;
+}
+
+/** The kinds mcpp advertised, i.e. which `--format json` commands are safe to use. */
+export function supportsKind(info: ProtocolInfo | undefined, kind: string): boolean {
+  if (info === undefined || typeof kind !== "string") {
+    return false;
+  }
+  const kinds = info.kinds;
+  if (typeof kinds !== "object" || kinds === null) {
+    return false;
+  }
+  return Object.prototype.hasOwnProperty.call(kinds, kind);
+}
+
+/** `parseEnvelope` and `kind` check in one step, returning `data` or `undefined`. */
+export function readData(stdout: string, kind: string): T | undefined {
+  const envelope = parseEnvelope(stdout);
+  if (envelope === undefined || envelope.kind !== kind) {
+    return undefined;
+  }
+  return envelope.data;
+}
diff --git a/src/cli/search.ts b/src/cli/search.ts
new file mode 100644
index 0000000..8cf21ef
--- /dev/null
+++ b/src/cli/search.ts
@@ -0,0 +1,175 @@
+// `mcpp search` 的适配层（依赖版本补全，方案默认关）。
+//
+// **这是全项目唯一解析「人类输出」的地方。** `mcpp search` 没有机读格式
+// （`--all-versions` 也只改人类列表的详细程度，不是 JSON），所以这里只能按
+// 实测行形状解析，并且必须防御性地失败：看不懂的行一律跳过，绝不抛异常、
+// 绝不半猜。mcpp 一旦提供机读格式就替换本模块（方案 §3.3.2 已登记）。
+//
+// 纯字符串函数：不启动进程、不读盘、不依赖 vscode。执行 `mcpp`、超时、联网
+// 判定与会话缓存都由调用方负责（`mcpp.toml.indexCompletion*`）。
+//
+// 实测形状（mcpp 2026.9.30.2）：
+//   兼容索引行   `  compat:zlib           A compression library  (1.3.2)`
+//   --all-versions 多版本   `  mcpplibs:aarch64-virt-rt  …  (0.2.1, 0.2.0, 0.1.1, ...)`
+//   没有版本的行（如纯 xim 工具）没有尾括号，直接跳过。
+
+export interface PackageVersion {
+  version: string;
+  summary?: string;
+}
+
+/** semver 近似：数字点分，可带 `-`/`+` 后缀（`2026.07.09` 这类日期版本也算）。 */
+const VERSION = /^\d+(?:\.\d+)*(?:[-+][0-9A-Za-z.-]+)?$/;
+/** 行尾的括号组：实测版本都写在这里。 */
+const TRAILING_PARENS = /\(([^()]*)\)\s*$/;
+/** 有些终端会给输出上色；颜色码不属于内容。 */
+const ANSI = /\u001b\[[0-9;]*m/g;
+
+function isVersionToken(text: string): boolean {
+  return VERSION.test(text);
+}
+
+/** 去掉包标识后的描述文本；没有描述时返回 undefined。 */
+function summaryOf(head: string): string | undefined {
+  const match = /^\S+\s+(.*)$/.exec(head.trim());
+  const summary = match?.[1]?.trim() ?? "";
+  return summary === "" ? undefined : summary;
+}
+
+/** 简单 semver 比较：数字段按数值比，缺段视为更小，后缀按字典序。 */
+function compareVersions(a: string, b: string): number {
+  const left = a.split(/[.+-]/);
+  const right = b.split(/[.+-]/);
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const l = left[index];
+    const r = right[index];
+    if (l === undefined) {
+      return -1;
+    }
+    if (r === undefined) {
+      return 1;
+    }
+    const ln = /^\d+$/.test(l) ? Number(l) : undefined;
+    const rn = /^\d+$/.test(r) ? Number(r) : undefined;
+    if (ln !== undefined && rn !== undefined) {
+      if (ln !== rn) {
+        return ln < rn ? -1 : 1;
+      }
+      continue;
+    }
+    const order = l.localeCompare(r);
+    if (order !== 0) {
+      return order < 0 ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/**
+ * 从 `mcpp search  --all-versions` 的 stdout 提取候选版本，
+ * 去重后按新→旧排序。空输入、只有旁白、或形状不认识时返回空数组。
+ */
+export function parseSearchOutput(stdout: string): PackageVersion[] {
+  if (typeof stdout !== "string" || stdout === "") {
+    return [];
+  }
+  const byVersion = new Map();
+  for (const rawLine of stdout.split(/\r?\n/)) {
+    const line = rawLine.replace(ANSI, "").trim();
+    if (line === "") {
+      continue;
+    }
+    const match = TRAILING_PARENS.exec(line);
+    if (match === null) {
+      continue;
+    }
+    const versions = match[1]
+      .split(",")
+      .map((part) => part.trim())
+      .filter(isVersionToken);
+    if (versions.length === 0) {
+      continue;
+    }
+    const summary = summaryOf(line.slice(0, match.index));
+    for (const version of versions) {
+      if (byVersion.has(version)) {
+        continue;
+      }
+      const entry: PackageVersion = { version };
+      if (summary !== undefined) {
+        entry.summary = summary;
+      }
+      byVersion.set(version, entry);
+    }
+  }
+  return [...byVersion.values()].sort((a, b) => compareVersions(b.version, a.version));
+}
+
+/** `mcpp` 的 argv（不含可执行文件名）。 */
+export function searchArguments(name: string): string[] {
+  return ["search", name, "--all-versions"];
+}
+
+/**
+ * 是否执行索引查询：显式开启、工作区受信任、且未离线。
+ * `name` 留给将来的 deny-list；当前判定只是三个开关的合取。
+ */
+export function shouldSearch(
+  name: string,
+  options: { enabled: boolean; offline: boolean; trusted: boolean },
+): boolean {
+  return options.enabled && options.trusted && !options.offline;
+}
+
+/** `mcpp.toml.indexCompletionTimeoutSeconds` 的注册表默认值。 */
+const DEFAULT_INDEX_TIMEOUT_SECONDS = 20;
+
+/** 一次索引查询的完整描述：argv 与硬超时。 */
+export interface IndexSearchRequest {
+  name: string;
+  args: string[];
+  timeoutMs: number;
+}
+
+/**
+ * 把设置解析成"要跑什么"，或者 `undefined` 表示不跑。
+ *
+ * 纯函数：进程、会话缓存、vscode 判定都在调用方（`src/toml/providers.ts`）。
+ * 超时从 `mcpp.toml.indexCompletionTimeoutSeconds` 来，至少 1 秒；非有限值
+ * 回落到注册表默认的 20 秒。这样"绝不超过设置的超时"有一个可单测的落点。
+ */
+export function indexCompletionRequest(
+  name: string,
+  options: { enabled: boolean; trusted: boolean; offline: boolean; timeoutSeconds: number },
+): IndexSearchRequest | undefined {
+  if (!shouldSearch(name, options)) {
+    return undefined;
+  }
+  const seconds = Number.isFinite(options.timeoutSeconds)
+    ? Math.max(1, Math.floor(options.timeoutSeconds))
+    : DEFAULT_INDEX_TIMEOUT_SECONDS;
+  return { name, args: searchArguments(name), timeoutMs: seconds * 1000 };
+}
+
+/**
+ * 等 `work`，但最多等 `timeoutMs`；超时得到 `undefined`。
+ *
+ * 调用方自己的进程超时（`execFile` 的 `timeout`）才是第一道闸；这是第二道：
+ * 即便进程卡住不退出，补全也必须在超时后返回，绝不把编辑器挂住。
+ */
+export async function withDeadline(work: Promise, timeoutMs: number): Promise {
+  let timer: ReturnType | undefined;
+  try {
+    return await Promise.race([
+      work,
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve(undefined), timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+  }
+}
diff --git a/src/cli/selfCheck.ts b/src/cli/selfCheck.ts
new file mode 100644
index 0000000..4f5f517
--- /dev/null
+++ b/src/cli/selfCheck.ts
@@ -0,0 +1,98 @@
+/**
+ * `mcpp: Environment Self-check` — one copyable snapshot.
+ *
+ * The point is to answer the questions a support thread always asks, in one
+ * place: which versions, which protocol, what mcppls can do, what the state is,
+ * which settings were changed. Pure, so the layout is testable and the extension
+ * host only has to gather the input.
+ */
+
+import { formatBytes, formatCount } from "../util/format";
+
+export interface SelfCheckInput {
+  extensionVersion: string;
+  vscodeVersion: string;
+  platform: string;
+  languagePreference: string;
+  trusted: boolean;
+  workspaceRoots: readonly string[];
+  projectRoot?: string;
+  mcppPath: string;
+  mcppProbe?: {
+    version?: string;
+    envelopeMax?: number;
+    kinds: readonly string[];
+    effects?: Record;
+  };
+  mcppls: {
+    installed: boolean;
+    version?: string;
+    enabled: boolean;
+    state: string;
+    capabilities: ReadonlyArray<{ key: string; state: string; command?: string }>;
+  };
+  cache?: { totalBytes: number; entries: number; incomplete?: number };
+  changedSettings: ReadonlyArray<{ key: string; value: unknown; source: string }>;
+  lastRefresh?: { at: string; state: string; command?: string };
+}
+
+function line(label: string, value: string): string {
+  return `  ${label.padEnd(14)}${value}`;
+}
+
+/**
+ * The snapshot. It says "unknown" where something could not be read — an empty
+ * field reads as "nothing is wrong", which is the opposite of the truth.
+ */
+export function buildSelfCheckText(input: SelfCheckInput): string {
+  const lines: string[] = [];
+  lines.push(`mcpp-vscode ${input.extensionVersion} · VS Code ${input.vscodeVersion} · ${input.platform}`);
+  lines.push(line("Language", input.languagePreference));
+  lines.push(line("Workspace", `${input.trusted ? "trusted" : "NOT trusted"} · ${input.workspaceRoots.length} root(s)`));
+  for (const root of input.workspaceRoots) {
+    lines.push(line("  folder", root));
+  }
+  lines.push(line("Project", input.projectRoot ?? "no mcpp.toml found"));
+
+  lines.push("");
+  lines.push("mcpp");
+  lines.push(line("path", input.mcppPath));
+  const probe = input.mcppProbe;
+  if (probe === undefined) {
+    lines.push(line("version", "unknown (mcpp --protocol-version did not answer)"));
+  } else {
+    lines.push(line("version", probe.version ?? "unknown"));
+    lines.push(line("envelope", probe.envelopeMax === undefined ? "unknown" : String(probe.envelopeMax)));
+    lines.push(line("kinds", probe.kinds.length === 0 ? "none advertised" : probe.kinds.join(", ")));
+  }
+
+  lines.push("");
+  lines.push("C++ Modules (mcppls)");
+  lines.push(line("installed", input.mcppls.installed ? "yes" : "no"));
+  lines.push(line("version", input.mcppls.version ?? "unknown"));
+  lines.push(line("enabled", input.mcppls.enabled ? "yes" : "disabled in this workspace"));
+  lines.push(line("state", input.mcppls.state));
+  for (const capability of input.mcppls.capabilities) {
+    lines.push(line(`  ${capability.key}`, `${capability.state}${capability.command === undefined ? "" : ` → ${capability.command}`}`));
+  }
+  lines.push(line("last refresh", input.lastRefresh === undefined ? "never" : `${input.lastRefresh.state} at ${input.lastRefresh.at}${input.lastRefresh.command === undefined ? "" : ` (${input.lastRefresh.command})`}`));
+
+  lines.push("");
+  lines.push("Cache");
+  if (input.cache === undefined) {
+    lines.push(line("shared", "not read"));
+  } else {
+    lines.push(line("shared", `${formatBytes(input.cache.totalBytes)} · ${formatCount(input.cache.entries)} entries${input.cache.incomplete === undefined ? "" : ` · ${input.cache.incomplete} incomplete`}`));
+  }
+
+  lines.push("");
+  lines.push(`Settings changed from their default (${input.changedSettings.length})`);
+  if (input.changedSettings.length === 0) {
+    lines.push(line("", "none"));
+  } else {
+    for (const entry of input.changedSettings) {
+      lines.push(line(`  ${entry.source}`, `${entry.key} = ${JSON.stringify(entry.value)}`));
+    }
+  }
+  return lines.join("\n");
+}
diff --git a/src/cli/statusBar.ts b/src/cli/statusBar.ts
new file mode 100644
index 0000000..e7fc67c
--- /dev/null
+++ b/src/cli/statusBar.ts
@@ -0,0 +1,45 @@
+/**
+ * The one thing the status bar item can be painted with.
+ *
+ * `StatusBarItem.backgroundColor` looks like it takes any `ThemeColor`, and the
+ * API reference says so — but the extension host enforces a whitelist, and it is
+ * the *host* that also swaps the foreground so the text stays readable:
+ *
+ * ```js
+ * // extensionHostProcess.js, ExtHostStatusBarEntry
+ * static ALLOWED_BACKGROUND_COLORS = new Map([
+ *   ["statusBarItem.errorBackground", new ThemeColor("statusBarItem.errorForeground")],
+ *   ["statusBarItem.warningBackground", new ThemeColor("statusBarItem.warningForeground")],
+ * ]);
+ * set backgroundColor(t) { t && !ALLOWED_BACKGROUND_COLORS.has(t.id) && (t = void 0); … }
+ * ```
+ *
+ * So a contributed `mcpp.statusBarBackground` would be silently dropped, and a
+ * `color` set alongside one of the two allowed backgrounds would be overridden.
+ * This module is the whole answer to "can the mcpp item have a background?" and
+ * it is pure, so the answer is testable without an editor host.
+ */
+
+/** The value of `mcpp.ui.statusBar.background`. */
+export type StatusBarBackground = "none" | "warning" | "error";
+
+/** Every value `mcpp.ui.statusBar.background` accepts, in menu order. */
+export const STATUS_BAR_BACKGROUNDS: readonly StatusBarBackground[] = ["warning", "error", "none"];
+
+/**
+ * The `ThemeColor` id for a setting value, or `undefined` for "no background".
+ *
+ * An unknown value is treated as `none` rather than as an error: a settings file
+ * with a stale value should leave the status bar plain, not throw during
+ * activation.
+ */
+export function statusBarBackgroundColour(value: unknown): string | undefined {
+  switch (value) {
+    case "warning":
+      return "statusBarItem.warningBackground";
+    case "error":
+      return "statusBarItem.errorBackground";
+    default:
+      return undefined;
+  }
+}
diff --git a/src/tasks.ts b/src/cli/tasks.ts
similarity index 68%
rename from src/tasks.ts
rename to src/cli/tasks.ts
index 912e692..a480b31 100644
--- a/src/tasks.ts
+++ b/src/cli/tasks.ts
@@ -1,3 +1,5 @@
+import { t } from "../i18n/t";
+
 export type ProjectTaskKind = "build" | "run" | "test" | "clean";
 export type TaskState = "succeeded" | "failed" | "cancelled";
 
@@ -12,18 +14,36 @@ export interface TaskCompletion {
   exitCode?: number;
 }
 
-const TASK_TITLES: Record = {
-  build: "mcpp: 构建",
-  run: "mcpp: 运行",
-  test: "mcpp: 测试",
-  clean: "mcpp: 清理",
+/**
+ * The task's display name. Resolved per call, not at import time, so a change to
+ * `mcpp.ui.language` applies without reloading the window.
+ */
+function taskTitle(kind: ProjectTaskKind): string {
+  switch (kind) {
+    case "build":
+      return t("mcpp: Build");
+    case "run":
+      return t("mcpp: Run");
+    case "test":
+      return t("mcpp: Test");
+    case "clean":
+      return t("mcpp: Clean");
+  }
+}
+
+/** `mcpp.task.Args`, so a user can pass `-j 4` or `--quiet` without a wrapper. */
+export const TASK_ARGUMENT_SETTINGS: Readonly> = {
+  build: "mcpp.task.buildArgs",
+  run: "mcpp.task.runArgs",
+  test: "mcpp.task.testArgs",
+  clean: "mcpp.task.cleanArgs",
 };
 
-export function projectTaskPlan(kind: ProjectTaskKind): ProjectTaskPlan {
+export function projectTaskPlan(kind: ProjectTaskKind, extraArgs: readonly string[] = []): ProjectTaskPlan {
   return {
     kind,
-    title: TASK_TITLES[kind],
-    args: [kind],
+    title: taskTitle(kind),
+    args: [kind, ...extraArgs],
   };
 }
 
diff --git a/src/cli.ts b/src/cli/toolchain.ts
similarity index 100%
rename from src/cli.ts
rename to src/cli/toolchain.ts
diff --git a/src/cliController.ts b/src/cliController.ts
deleted file mode 100644
index 79e9fc9..0000000
--- a/src/cliController.ts
+++ /dev/null
@@ -1,759 +0,0 @@
-import { existsSync } from "node:fs";
-import { join } from "node:path";
-import process from "node:process";
-
-import * as vscode from "vscode";
-
-import {
-  hostDefaultToolchains,
-  mcppCommandArguments,
-  normalizeToolchainSpec,
-  parseToolchainList,
-  toolchainInstallKind,
-  toolchainSpecTargetHint,
-  type ToolchainInventory,
-  type ToolchainItem,
-} from "./cli";
-import type { McppProjectDiscovery } from "./discovery";
-import { runProcess } from "./process";
-import {
-  McppOperationRegistry,
-  classifyTaskExit,
-  projectTaskPlan,
-  shouldRefreshLanguageServerAfterTask,
-  type ProjectTaskKind,
-  type TaskCompletion,
-} from "./tasks";
-import { CLI_COMMANDS, quickMenuItems, quickMenuStatusText } from "./commands";
-import { runNewProjectFlow, validateNewProjectName } from "./newProject";
-
-export interface McppCliControllerOptions {
-  output: vscode.OutputChannel;
-  currentProject: () => McppProjectDiscovery | undefined;
-  afterProjectTask: (
-    project: McppProjectDiscovery,
-    kind: ProjectTaskKind,
-    completion: TaskCompletion,
-  ) => Promise;
-  isTrusted: () => boolean;
-}
-
-interface ToolchainPickItem extends vscode.QuickPickItem {
-  spec?: string;
-  toolchain?: ToolchainItem;
-  customInput?: boolean;
-}
-
-type OperationToken = object;
-
-export interface ProjectTaskRunOptions {
-  /** Set to false when the caller performs its own post-task action. */
-  notify?: boolean;
-}
-
-const INSTALL_CUSTOM_LABEL = "$(edit) 输入其他兼容工具链 spec…";
-const CONFIRM_INSTALL = "安装";
-const CONFIRM_DETECT = "检测";
-const CONFIRM_DEFAULT = "设为全局默认";
-const CONFIRM_CLEAN = "清理 target";
-const SHOW_TASKS = "显示正在运行的任务";
-
-function taskScope(root: string): vscode.WorkspaceFolder | vscode.TaskScope {
-  return vscode.workspace.getWorkspaceFolder(vscode.Uri.file(root))
-    ?? vscode.TaskScope.Workspace;
-}
-
-function workingDirectory(project: McppProjectDiscovery | undefined): string {
-  if (project !== undefined) {
-    return project.root;
-  }
-  return vscode.workspace.workspaceFolders?.[0]?.uri.fsPath ?? process.cwd();
-}
-
-function commandLine(executable: string, args: string[]): string {
-  return [executable, ...args].join(" ");
-}
-
-export class McppCliController {
-  private readonly status: vscode.StatusBarItem;
-
-  private readonly operations = new McppOperationRegistry();
-
-  public constructor(private readonly options: McppCliControllerOptions) {
-    this.status = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 40);
-    this.status.command = CLI_COMMANDS.showMenu;
-    this.status.text = quickMenuStatusText;
-    this.status.tooltip = "打开 mcpp 项目和工具链快捷菜单";
-  }
-
-  public register(): vscode.Disposable[] {
-    const disposables: vscode.Disposable[] = [
-      this.status,
-      vscode.commands.registerCommand(CLI_COMMANDS.showMenu, this.guarded(() => this.showMenu())),
-      vscode.commands.registerCommand(CLI_COMMANDS.newProject, this.guarded(() => this.newProject())),
-      vscode.commands.registerCommand(CLI_COMMANDS.build, this.guarded(() => this.runProjectTask("build"))),
-      vscode.commands.registerCommand(CLI_COMMANDS.run, this.guarded(() => this.runProjectTask("run"))),
-      vscode.commands.registerCommand(CLI_COMMANDS.test, this.guarded(() => this.runProjectTask("test"))),
-      vscode.commands.registerCommand(CLI_COMMANDS.clean, this.guarded(() => this.runProjectTask("clean"))),
-      vscode.commands.registerCommand(CLI_COMMANDS.showToolchains, this.guarded(() => this.showToolchains())),
-      vscode.commands.registerCommand(CLI_COMMANDS.installToolchain, this.guarded(() => this.installToolchain())),
-      vscode.commands.registerCommand(CLI_COMMANDS.selectDefaultToolchain, this.guarded(() => this.selectDefaultToolchain())),
-      vscode.window.onDidChangeActiveTextEditor(() => this.refreshStatus()),
-      vscode.workspace.onDidChangeWorkspaceFolders(() => this.refreshStatus()),
-    ];
-    this.refreshStatus();
-    return disposables;
-  }
-
-  public refreshStatus(): void {
-    if (this.options.currentProject() === undefined) {
-      this.status.hide();
-      return;
-    }
-    this.status.show();
-  }
-
-  public isBusy(): boolean {
-    return this.operations.hasActive();
-  }
-
-  public async runProjectTask(
-    kind: ProjectTaskKind,
-    options: ProjectTaskRunOptions = {},
-  ): Promise {
-    const project = this.requireProject();
-    if (project === undefined || !this.requireTrusted()) {
-      return undefined;
-    }
-
-    if (kind === "clean") {
-      const choice = await vscode.window.showWarningMessage(
-        `将删除当前工程的 target 目录：${project.root}/target`,
-        { modal: true, detail: "此操作不会清理全局 BMI 缓存。" },
-        CONFIRM_CLEAN,
-      );
-      if (choice !== CONFIRM_CLEAN) {
-        return undefined;
-      }
-    }
-
-    const token: OperationToken = {};
-    const active = this.operations.beginProject(project.root, token);
-    if (active !== undefined) {
-      const choice = await vscode.window.showWarningMessage(
-        `已有 mcpp 操作正在运行，暂不启动 ${kind}。`,
-        SHOW_TASKS,
-      );
-      if (choice === SHOW_TASKS) {
-        await vscode.commands.executeCommand("workbench.action.tasks.showTasks");
-      }
-      return undefined;
-    }
-
-    let completion: TaskCompletion | undefined;
-    try {
-      const plan = projectTaskPlan(kind);
-      completion = await this.executeTask(
-        project.root,
-        this.mcppExecutable(project),
-        plan.title,
-        plan.args,
-      );
-      this.appendTaskCompletion(project.root, plan.title, plan.args, completion);
-    } finally {
-      this.operations.finishProject(project.root, token);
-    }
-
-    if (options.notify !== false
-      && completion !== undefined
-      && shouldRefreshLanguageServerAfterTask(kind, completion)) {
-      await this.options.afterProjectTask(project, kind, completion);
-    }
-    return completion;
-  }
-
-  public async showToolchains(): Promise {
-    if (!this.requireTrusted()) {
-      return;
-    }
-    const project = this.options.currentProject();
-    const inventory = await this.readToolchainInventory(project);
-    if (inventory === undefined) {
-      return;
-    }
-
-    const items = this.inventoryItems(inventory, false, project);
-    if (items.length === 0) {
-      await vscode.window.showInformationMessage(
-        "mcpp 没有列出可用工具链；请查看 mcpp 输出频道中的原始结果。",
-      );
-      return;
-    }
-    await vscode.window.showQuickPick(items, {
-      title: "mcpp 工具链与 target",
-      placeHolder: "只读查看 mcpp 当前解析结果",
-      matchOnDescription: true,
-      matchOnDetail: true,
-    });
-  }
-
-  public async installToolchain(): Promise {
-    if (!this.requireTrusted()) {
-      return;
-    }
-    const project = this.options.currentProject();
-    const inventory = await this.readToolchainInventory(project);
-    const spec = await this.pickInstallSpec(inventory);
-    if (spec === undefined) {
-      return;
-    }
-    const installKind = toolchainInstallKind(spec);
-    const targetHint = toolchainSpecTargetHint(spec);
-    const confirmLabel = installKind === "system-detect" ? CONFIRM_DETECT : CONFIRM_INSTALL;
-    const confirmation = installKind === "system-detect"
-      ? `将调用 mcpp 检测系统 MSVC（${spec}）。`
-      : targetHint === "target"
-        ? `将把可能携带 target 语义的兼容 spec ${spec} 交给 mcpp 安装，最终由 mcpp 校验。`
-        : installKind === "managed-target"
-          ? `将把携带 target 语义的兼容 spec ${spec} 交给 mcpp 安装。`
-          : `将安装 mcpp 工具链 ${spec}（不指定 target，使用 host target）。`;
-    const detail = installKind === "system-detect"
-      ? "mcpp 不会下载或安装 MSVC；它会检测 Visual Studio，并在缺失时给出官方安装指引。"
-      : targetHint === "target"
-        ? "mcpp 会判断编译器前缀是否为有效 triple；有效时可能下载对应 target 的较大工具链包。"
-        : installKind === "managed-target"
-          ? "mcpp 会规范化兼容写法，并可能下载对应 target 的较大工具链包。"
-          : "安装可能下载较大的工具链包，并修改 mcpp 全局缓存。";
-
-    const choice = await vscode.window.showWarningMessage(
-      confirmation,
-      { modal: true, detail },
-      confirmLabel,
-    );
-    if (choice !== confirmLabel) {
-      return;
-    }
-
-    const token: OperationToken = {};
-    const active = this.operations.beginGlobal(token);
-    if (active !== undefined) {
-      const duplicateChoice = await vscode.window.showWarningMessage(
-        "已有 mcpp 操作正在运行。",
-        SHOW_TASKS,
-      );
-      if (duplicateChoice === SHOW_TASKS) {
-        await vscode.commands.executeCommand("workbench.action.tasks.showTasks");
-      }
-      return;
-    }
-
-    const taskTitle = installKind === "system-detect"
-      ? `mcpp: 检测系统 MSVC（${spec}）`
-      : `mcpp: 安装工具链 ${spec}`;
-    try {
-      const installArgs = mcppCommandArguments("toolchain", "install", spec);
-      const completion = await this.executeTask(
-        workingDirectory(project),
-        this.mcppExecutable(project),
-        taskTitle,
-        installArgs,
-      );
-      this.appendTaskCompletion(
-        workingDirectory(project),
-        taskTitle,
-        installArgs,
-        completion,
-      );
-      if (completion.state !== "succeeded") {
-        return;
-      }
-    } finally {
-      this.operations.finishGlobal(token);
-    }
-
-    if (installKind === "managed-target") {
-      await vscode.window.showInformationMessage(
-        `mcpp 已完成 ${spec}。首版插件不修改 target 默认；如需设为默认，请使用带 --target 的 mcpp CLI。`,
-      );
-      return;
-    }
-
-    const refreshed = await this.readToolchainInventory(project);
-    const defaultChoice = await vscode.window.showInformationMessage(
-      installKind === "system-detect"
-        ? "MSVC 检测完成。是否从最新列表中选择全局默认？"
-        : `工具链 ${spec} 安装完成。是否从最新列表中选择全局默认？`,
-      "选择全局默认",
-    );
-    if (defaultChoice === "选择全局默认" && refreshed !== undefined) {
-      await this.selectDefaultToolchainFromInventory(project, refreshed);
-    }
-  }
-
-  public async selectDefaultToolchain(): Promise {
-    if (!this.requireTrusted()) {
-      return;
-    }
-    const project = this.options.currentProject();
-    const inventory = await this.readToolchainInventory(project);
-    if (inventory !== undefined) {
-      await this.selectDefaultToolchainFromInventory(project, inventory);
-    }
-  }
-
-  private async selectDefaultToolchainFromInventory(
-    project: McppProjectDiscovery | undefined,
-    inventory: ToolchainInventory,
-  ): Promise {
-    const installed = hostDefaultToolchains(inventory);
-    if (installed.length === 0) {
-      await vscode.window.showWarningMessage(
-        "没有可用于 host target 的已安装工具链，不能在此处设置全局默认。target 专用工具链请使用 mcpp CLI；Windows MSVC 请先安装 Visual Studio。",
-      );
-      return;
-    }
-
-    const items: ToolchainPickItem[] = installed.map((toolchain) => ({
-      label: `${toolchain.effective ? "$(check) " : ""}${toolchain.spec}`,
-      description: toolchain.source === "system" ? "系统工具链（mcpp 只检测）" : "mcpp 管理的工具链",
-      detail: toolchain.effective ? "当前工程有效工具链" : undefined,
-      spec: toolchain.spec,
-      toolchain,
-    }));
-    const picked = await vscode.window.showQuickPick(items, {
-      title: "选择 mcpp 全局默认工具链",
-      placeHolder: this.isNestedWorkspaceProject(project)
-        ? "当前工程根位于 VS Code 文件夹子目录；实际构建解析以 mcpp 为准"
-        : inventory.projectOverridesGlobal
-          ? "项目当前覆盖全局默认；这里只修改 mcpp 当前全局配置"
-          : "选择后只修改 mcpp 全局配置，不会自动构建工程",
-      matchOnDescription: true,
-      matchOnDetail: true,
-    });
-    if (picked?.spec === undefined) {
-      return;
-    }
-
-    const choice = await vscode.window.showWarningMessage(
-      `将把全局默认对设为 ${picked.spec} + host target。当前项目的 mcpp.toml/target 配置仍可能覆盖它。`,
-      { modal: true, detail: "mcpp 会同时清空全局 default_target；配置文件位置由当前 mcpp 安装及 MCPP_HOME 决定。" },
-      CONFIRM_DEFAULT,
-    );
-    if (choice !== CONFIRM_DEFAULT) {
-      return;
-    }
-
-    const token: OperationToken = {};
-    const active = this.operations.beginGlobal(token);
-    if (active !== undefined) {
-      await vscode.window.showWarningMessage("已有 mcpp 操作正在运行。", SHOW_TASKS);
-      return;
-    }
-
-    try {
-      const args = mcppCommandArguments("toolchain", "default", picked.spec);
-      const result = await runProcess(
-        this.mcppExecutable(project),
-        args,
-        workingDirectory(project),
-      );
-      this.appendShortCommand("设置全局默认工具链", this.mcppExecutable(project), args, result);
-      if (result.exitCode !== 0) {
-        await vscode.window.showErrorMessage(
-          `设置全局默认工具链失败（退出码 ${result.exitCode}）。请查看 mcpp 输出频道。`,
-        );
-        return;
-      }
-
-    } finally {
-      this.operations.finishGlobal(token);
-    }
-
-    const buildChoice = await vscode.window.showInformationMessage(
-      `mcpp 全局默认已更新为 ${picked.spec} + host target。建议清理旧工具链产物后重新构建。`,
-      ...(project === undefined ? [] : ["清理并构建"]),
-    );
-    if (buildChoice === "清理并构建" && project !== undefined) {
-      const cleanArgs = mcppCommandArguments("clean");
-      const cleanResult = await runProcess(this.mcppExecutable(project), cleanArgs, project.root);
-      this.appendShortCommand("清理旧产物", this.mcppExecutable(project), cleanArgs, cleanResult);
-      await this.runProjectTask("build");
-    }
-  }
-
-  private async pickInstallSpec(inventory: ToolchainInventory | undefined): Promise {
-    const items: ToolchainPickItem[] = [];
-    for (const toolchain of inventory?.available ?? []) {
-      items.push({
-        label: toolchain.spec,
-        description: "mcpp 按 family 聚合的可用版本；本操作按 host target 安装",
-        spec: toolchain.spec,
-      });
-    }
-    items.push({
-      label: INSTALL_CUSTOM_LABEL,
-      detail: "支持 family、family@version、namespace、部分版本和 mcpp 兼容旧拼写",
-      customInput: true,
-    });
-
-    const picked = await vscode.window.showQuickPick(items, {
-      title: "安装 mcpp 工具链",
-      placeHolder: "不选择 target；target 专用安装请使用 mcpp CLI",
-      matchOnDescription: true,
-      matchOnDetail: true,
-    });
-    if (picked === undefined) {
-      return undefined;
-    }
-    if (!picked.customInput) {
-      return picked.spec;
-    }
-
-    const input = await vscode.window.showInputBox({
-      title: "输入工具链 spec",
-      prompt: "例如 gcc、llvm@20.1.7、xim:gcc@16、msvc、mingw；兼容写法由 mcpp 规范化",
-      placeHolder: "gcc@16",
-      validateInput: (value) => {
-        const normalized = normalizeToolchainSpec(value);
-        if (normalized === undefined) {
-          return "请输入 family、family@version、family version、namespace 或 mcpp 兼容 spec";
-        }
-        return undefined;
-      },
-    });
-    return input === undefined ? undefined : normalizeToolchainSpec(input);
-  }
-
-  private inventoryItems(
-    inventory: ToolchainInventory,
-    includeActions: boolean,
-    project: McppProjectDiscovery | undefined,
-  ): ToolchainPickItem[] {
-    const items: ToolchainPickItem[] = [];
-    const nestedView = this.isNestedWorkspaceProject(project);
-    if (inventory.effective !== undefined) {
-      items.push({
-        label: `$(check) ${nestedView ? "mcpp list 当前目录工具链" : "当前有效工具链"}：${inventory.effective.spec}`,
-        description: nestedView
-          ? "当前目录视图；实际生效值以 mcpp build 解析为准"
-          : inventory.projectOverridesGlobal ? "来自当前项目 mcpp.toml，覆盖全局默认" : "来自全局默认",
-        detail: inventory.effectiveTarget === undefined
-          ? "有效 target：host（mcpp 未显示显式 target）"
-          : `有效 target：${inventory.effectiveTarget}`,
-      });
-    }
-    if (inventory.globalDefaultSpec !== undefined) {
-      items.push({
-        label: `全局默认：${inventory.globalDefaultSpec}`,
-        description: nestedView
-          ? "当前目录视图；项目或父级配置的覆盖以实际构建为准"
-          : inventory.projectOverridesGlobal ? "当前项目可能没有使用此值" : "mcpp 全局配置",
-      });
-    } else if (inventory.recognized) {
-      items.push({
-        label: "全局默认：",
-        description: "mcpp 尚未设置全局默认工具链",
-      });
-    }
-    for (const toolchain of inventory.installed) {
-      items.push({
-        label: `${toolchain.effective ? "$(check) " : ""}${toolchain.spec}`,
-        description: toolchain.source === "system" ? "System：系统工具链，仅检测" : "已安装",
-        detail: toolchain.effective
-          ? nestedView ? "mcpp list 当前目录有效项；实际构建解析可能受父级 mcpp 工作区影响" : "当前有效项"
-          : undefined,
-        spec: toolchain.spec,
-        toolchain,
-      });
-    }
-    for (const target of inventory.targets) {
-      items.push({
-        label: `${target.effective ? "$(check) " : ""}target ${target.target}`,
-        description: `${target.status}${target.toolchainSpec === undefined ? "" : ` · 约定 ${target.toolchainSpec}`}`,
-        detail: target.note.length === 0 ? "target 轴只读展示；选择 target 请使用 mcpp CLI" : target.note,
-      });
-    }
-    for (const toolchain of inventory.available) {
-      items.push({
-        label: `可安装：${toolchain.spec}`,
-        description: "mcpp 按 family 聚合的索引版本；未承诺 host payload",
-        spec: toolchain.spec,
-      });
-    }
-    if (includeActions) {
-      items.push({
-        label: "$(cloud-download) 安装工具链…",
-        detail: "回到工具链安装流程",
-        customInput: true,
-      });
-    }
-    return items;
-  }
-
-  private async showMenu(): Promise {
-    const items = quickMenuItems.map((item) => ({
-      label: item.label,
-      description: item.group === "project"
-        ? "当前 mcpp 工程"
-        : item.group === "toolchain" ? "mcpp 工具链管理" : "C++ Modules 语言服务",
-      command: item.command,
-    }));
-    const picked = await vscode.window.showQuickPick(items, {
-      title: "mcpp 快捷菜单",
-      placeHolder: "选择项目、工具链或 IDE 操作",
-      matchOnDescription: true,
-    });
-    if (picked !== undefined) {
-      await vscode.commands.executeCommand(picked.command);
-    }
-  }
-
-  public async newProject(): Promise {
-    if (!this.requireTrusted()) {
-      return;
-    }
-
-    const input = await vscode.window.showInputBox({
-      title: "新建 mcpp 工程（1/2）",
-      prompt: "输入项目名，将在所选位置创建同名项目文件夹",
-      placeHolder: "hello-mcpp",
-      validateInput: validateNewProjectName,
-    });
-    if (input === undefined) {
-      return;
-    }
-    const projectName = input.trim();
-
-    const picked = await vscode.window.showOpenDialog({
-      title: "选择项目位置（2/2）",
-      canSelectFiles: false,
-      canSelectFolders: true,
-      canSelectMany: false,
-      openLabel: "在此创建项目",
-    });
-    const location = picked?.[0];
-    if (location === undefined) {
-      return;
-    }
-
-    const projectRoot = join(location.fsPath, projectName);
-    const confirmCreate = "创建并打开";
-    await runNewProjectFlow(projectName, location.fsPath, projectRoot, {
-      exists: existsSync,
-      confirm: async (message) =>
-        (await vscode.window.showWarningMessage(message, { modal: true }, confirmCreate))
-        === confirmCreate,
-      run: async (name, cwd) => {
-        const executable = this.mcppExecutable(undefined);
-        const args = mcppCommandArguments("new", name);
-        const result = await runProcess(executable, args, cwd);
-        this.appendShortCommand("新建工程", executable, args, result);
-        return result.exitCode;
-      },
-      openFolder: async (path) => {
-        await vscode.commands.executeCommand("vscode.openFolder", vscode.Uri.file(path));
-      },
-      showError: async (message) => {
-        await vscode.window.showErrorMessage(message);
-      },
-    });
-  }
-
-  private guarded(operation: () => Promise): () => Promise {
-    return async () => {
-      try {
-        await operation();
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        try {
-          this.options.output.appendLine(`mcpp CLI 操作失败：${message}`);
-        } catch {
-          // 输出频道可能已经在窗口重载时释放。
-        }
-        await vscode.window.showErrorMessage(`mcpp：${message}`);
-      }
-    };
-  }
-
-  private requireProject(): McppProjectDiscovery | undefined {
-    const project = this.options.currentProject();
-    if (project === undefined) {
-      void vscode.window.showWarningMessage("当前工作区没有找到 mcpp.toml。请在 mcpp 工程中执行此命令。");
-    }
-    return project;
-  }
-
-  private requireTrusted(): boolean {
-    if (this.options.isTrusted()) {
-      return true;
-    }
-    void vscode.window.showWarningMessage(
-      "当前工作区未受信任。mcpp 命令可能执行工作区设置指定的外部程序，请先信任工作区。",
-    );
-    return false;
-  }
-
-  public mcppExecutable(project: McppProjectDiscovery | undefined): string {
-    const uri = project === undefined
-      ? vscode.workspace.workspaceFolders?.[0]?.uri
-      : vscode.Uri.file(project.root);
-    const configured = vscode.workspace.getConfiguration("mcpp", uri).get("path", "").trim();
-    return configured.length === 0 ? "mcpp" : configured;
-  }
-
-  private isNestedWorkspaceProject(project: McppProjectDiscovery | undefined): boolean {
-    if (project === undefined) {
-      return false;
-    }
-    const folder = vscode.workspace.getWorkspaceFolder(vscode.Uri.file(project.root));
-    return folder !== undefined && folder.uri.fsPath !== project.root;
-  }
-
-  public async readToolchainInventory(
-    project: McppProjectDiscovery | undefined = this.options.currentProject(),
-  ): Promise {
-    const executable = this.mcppExecutable(project);
-    const args = mcppCommandArguments("toolchain", "list");
-    const result = await runProcess(executable, args, workingDirectory(project));
-    this.appendShortCommand("查看工具链", executable, args, result);
-    if (result.exitCode !== 0) {
-      await vscode.window.showErrorMessage(
-        `mcpp toolchain list 失败（退出码 ${result.exitCode}）。请查看 mcpp 输出频道。`,
-      );
-      return undefined;
-    }
-
-    const inventory = parseToolchainList(`${result.stdout}${result.stderr.length > 0 ? `\n${result.stderr}` : ""}`);
-    if (!inventory.recognized) {
-      await vscode.window.showErrorMessage(
-        "无法识别当前 mcpp toolchain list 输出；原始输出已保留在 mcpp 输出频道，请检查 mcpp 版本。",
-      );
-      return undefined;
-    }
-    return inventory;
-  }
-
-  private async executeTask(
-    root: string,
-    executable: string,
-    title: string,
-    args: string[],
-  ): Promise {
-    const task = new vscode.Task(
-      { type: "mcpp", command: args[0] ?? "mcpp", projectRoot: root },
-      taskScope(root),
-      title,
-      "mcpp",
-      new vscode.ProcessExecution(executable, args, { cwd: root }),
-    );
-    task.presentationOptions = {
-      reveal: vscode.TaskRevealKind.Always,
-      panel: vscode.TaskPanelKind.Dedicated,
-      focus: true,
-      clear: true,
-      showReuseMessage: false,
-    };
-
-    let execution: vscode.TaskExecution | undefined;
-    let earlyCompletion: TaskCompletion | undefined;
-    let settled = false;
-    let processEndSubscription: vscode.Disposable | undefined;
-    let taskEndSubscription: vscode.Disposable | undefined;
-    const disposeListeners = (): void => {
-      processEndSubscription?.dispose();
-      taskEndSubscription?.dispose();
-    };
-    const finish = (completion: TaskCompletion): void => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      disposeListeners();
-      resolveCompletion?.(completion);
-    };
-    let resolveCompletion: ((completion: TaskCompletion) => void) | undefined;
-    const completion = new Promise((resolve) => {
-      resolveCompletion = resolve;
-      processEndSubscription = vscode.tasks.onDidEndTaskProcess((event) => {
-        if (event.execution.task !== task) {
-          return;
-        }
-        const classified = classifyTaskExit(event.exitCode);
-        if (execution === undefined) {
-          earlyCompletion ??= classified;
-          return;
-        }
-        finish(classified);
-      });
-      taskEndSubscription = vscode.tasks.onDidEndTask((event) => {
-        if (event.execution.task !== task) {
-          return;
-        }
-        const classified = classifyTaskExit(undefined);
-        if (execution === undefined) {
-          earlyCompletion ??= classified;
-          return;
-        }
-        finish(classified);
-      });
-    });
-
-    try {
-      execution = await vscode.tasks.executeTask(task);
-    } catch (error) {
-      disposeListeners();
-      throw error;
-    }
-    if (earlyCompletion !== undefined) {
-      finish(earlyCompletion);
-    }
-    return completion;
-  }
-
-  private appendTaskCompletion(
-    root: string,
-    title: string,
-    args: string[],
-    completion: TaskCompletion,
-  ): void {
-    const suffix = completion.state === "succeeded"
-      ? `退出码 ${completion.exitCode ?? 0}`
-      : completion.state === "cancelled"
-        ? "已取消"
-        : `失败，退出码 ${completion.exitCode ?? "未知"}`;
-    try {
-      this.options.output.appendLine(`\n[${new Date().toISOString()}] ${title}`);
-      this.options.output.appendLine(`工作目录：${root}`);
-      this.options.output.appendLine(`任务参数：${args.join(" ")}`);
-      this.options.output.appendLine(`结果：${suffix}`);
-    } catch {
-      // 窗口重载时输出频道可能早于任务事件被释放。
-    }
-    if (completion.state === "failed") {
-      void vscode.window.showErrorMessage(`${title}失败（退出码 ${completion.exitCode ?? "未知"}）。请查看任务终端。`);
-    } else if (completion.state === "cancelled") {
-      void vscode.window.showWarningMessage(`${title}已取消。`);
-    }
-  }
-
-  private appendShortCommand(
-    title: string,
-    executable: string,
-    args: string[],
-    result: { exitCode: number; stdout: string; stderr: string },
-  ): void {
-    try {
-      this.options.output.appendLine(`\n[${new Date().toISOString()}] ${title}`);
-      this.options.output.appendLine(`$ ${commandLine(executable, args)}`);
-      if (result.stdout.length > 0) {
-        this.options.output.appendLine(result.stdout.trimEnd());
-      }
-      if (result.stderr.length > 0) {
-        this.options.output.appendLine(result.stderr.trimEnd());
-      }
-      this.options.output.appendLine(`[exit ${result.exitCode}]`);
-    } catch {
-      // 窗口重载时输出频道可能早于短命令结束被释放。
-    }
-  }
-}
diff --git a/src/commands.ts b/src/commands.ts
deleted file mode 100644
index eb60afe..0000000
--- a/src/commands.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-export const CLI_COMMANDS = {
-  showMenu: "mcpp.showMenu",
-  newProject: "mcpp.newProject",
-  build: "mcpp.build",
-  run: "mcpp.run",
-  test: "mcpp.test",
-  clean: "mcpp.clean",
-  showToolchains: "mcpp.showToolchains",
-  installToolchain: "mcpp.installToolchain",
-  selectDefaultToolchain: "mcpp.selectDefaultToolchain",
-  configureLanguageServer: "mcpp.configureLanguageServer",
-  refreshCompilationDatabase: "mcpp.refreshCompilationDatabase",
-  checkModuleSupport: "mcpp.checkModuleSupport",
-  autoConfigureModules: "mcpp.autoConfigureModules",
-  showModuleGraph: "mcpp.showModuleGraph",
-  showLanguageServerLogs: "mcpp.showLanguageServerLogs",
-} as const;
-
-export const DEPRECATED_COMMANDS = {
-  configureClangd: "mcpp.configureClangd",
-} as const;
-
-export const quickMenuStatusText = "$(tools) mcpp: 快捷菜单";
-
-export interface QuickMenuItem {
-  label: string;
-  command: string;
-  group: "project" | "toolchain" | "ide";
-}
-
-export const quickMenuItems: readonly QuickMenuItem[] = [
-  { label: "$(gear) 构建", command: CLI_COMMANDS.build, group: "project" },
-  { label: "$(play) 运行", command: CLI_COMMANDS.run, group: "project" },
-  { label: "$(beaker) 测试", command: CLI_COMMANDS.test, group: "project" },
-  { label: "$(trash) 清理 target", command: CLI_COMMANDS.clean, group: "project" },
-  { label: "$(list-unordered) 查看工具链", command: CLI_COMMANDS.showToolchains, group: "toolchain" },
-  { label: "$(cloud-download) 安装工具链", command: CLI_COMMANDS.installToolchain, group: "toolchain" },
-  { label: "$(settings-gear) 选择全局默认工具链", command: CLI_COMMANDS.selectDefaultToolchain, group: "toolchain" },
-  { label: "$(symbol-interface) 选择 C++ 模块分析上下文", command: CLI_COMMANDS.configureLanguageServer, group: "ide" },
-  { label: "$(database) 刷新模块构建描述", command: CLI_COMMANDS.refreshCompilationDatabase, group: "ide" },
-  { label: "$(check) 重启 C++ Modules 语言服务", command: CLI_COMMANDS.checkModuleSupport, group: "ide" },
-  { label: "$(type-hierarchy) 查看模块图", command: CLI_COMMANDS.showModuleGraph, group: "ide" },
-  { label: "$(output) 打开 C++ Modules 日志", command: CLI_COMMANDS.showLanguageServerLogs, group: "ide" },
-  { label: "$(rocket) 一键构建并刷新模块语言服务", command: CLI_COMMANDS.autoConfigureModules, group: "ide" },
-];
diff --git a/src/commands/ids.ts b/src/commands/ids.ts
new file mode 100644
index 0000000..fc08ce9
--- /dev/null
+++ b/src/commands/ids.ts
@@ -0,0 +1,114 @@
+/**
+ * Every command id this extension contributes, in one place.
+ *
+ * Two rules live here:
+ *
+ * 1. **`mcpp.` only.** Our ids must never collide with a command the C++ Modules
+ *    server advertises (`mcppls.*`): `vscode-languageclient` registers those
+ *    itself, and a duplicate id stops the language client from starting
+ *    (mcppls's S3-5.6-3). `test/mcppls/contract.test.ts` asserts this.
+ * 2. **Ids do not change once shipped.** A rename keeps the old id and points it
+ *    at the new implementation, so a user's keybinding keeps working — see
+ *    `DEPRECATED_COMMANDS` below.
+ */
+
+/** mcpp CLI commands that existed in 0.4.x. */
+export const CLI_COMMANDS = {
+  showMenu: "mcpp.showMenu",
+  newProject: "mcpp.newProject",
+  build: "mcpp.build",
+  run: "mcpp.run",
+  test: "mcpp.test",
+  clean: "mcpp.clean",
+  showToolchains: "mcpp.showToolchains",
+  installToolchain: "mcpp.installToolchain",
+  selectDefaultToolchain: "mcpp.selectDefaultToolchain",
+  autoConfigureModules: "mcpp.autoConfigureModules",
+} as const;
+
+/** The language-service entries that existed in 0.4.x (kept as aliases, see below). */
+export const LEGACY_LANGUAGE_SERVER_COMMANDS = {
+  configureLanguageServer: "mcpp.configureLanguageServer",
+  refreshCompilationDatabase: "mcpp.refreshCompilationDatabase",
+  checkModuleSupport: "mcpp.checkModuleSupport",
+  showModuleGraph: "mcpp.showModuleGraph",
+  showLanguageServerLogs: "mcpp.showLanguageServerLogs",
+} as const;
+
+/** The C++ Modules view and everything it forwards. */
+export const LANGUAGE_SERVER_COMMANDS = {
+  refreshState: "mcpp.languageServer.refreshState",
+  restart: "mcpp.languageServer.restart",
+  restartEngine: "mcpp.languageServer.restartEngine",
+  resetWorkspaceCache: "mcpp.languageServer.resetWorkspaceCache",
+  selectContext: "mcpp.languageServer.selectContext",
+  showModuleGraph: "mcpp.languageServer.showModuleGraph",
+  showLogs: "mcpp.languageServer.showLogs",
+  collectReport: "mcpp.languageServer.collectReport",
+  exportDiagnosticBundle: "mcpp.languageServer.exportDiagnosticBundle",
+  revealBundle: "mcpp.languageServer.revealBundle",
+  openLogFolder: "mcpp.languageServer.openLogFolder",
+  runBuildToolInTerminal: "mcpp.languageServer.runBuildToolInTerminal",
+  manageConflicts: "mcpp.languageServer.manageConflicts",
+  toggleInWorkspace: "mcpp.languageServer.toggleInWorkspace",
+  installTools: "mcpp.languageServer.installTools",
+  reviewChanges: "mcpp.languageServer.reviewChanges",
+} as const;
+
+/** Cache statistics and the cleanup table. */
+export const CACHE_COMMANDS = {
+  refreshStats: "mcpp.refreshCacheStats",
+  showEntry: "mcpp.showCacheEntry",
+  cleanStale: "mcpp.cleanStaleArtifacts",
+  cleanProject: "mcpp.cleanProjectArtifacts",
+  collect: "mcpp.gcGlobalCache",
+  prune: "mcpp.pruneGlobalCache",
+  verify: "mcpp.verifyGlobalCache",
+  cleanLegacy: "mcpp.cleanLegacyCache",
+} as const;
+
+/**
+ * The library-ecosystem view. The list and the detail page talk to their
+ * webviews over messages, so these are the only ids a menu can name.
+ */
+export const LIBRARY_COMMANDS = {
+  search: "mcpp.library.search",
+  openDetail: "mcpp.library.openDetail",
+  updateIndex: "mcpp.library.updateIndex",
+} as const;
+
+/** Settings, diagnostics and the mcpp CLI entry points added in 0.5.0. */
+export const TOOL_COMMANDS = {
+  openSettings: "mcpp.openSettings",
+  openLanguageServerSettings: "mcpp.openMcpplsSettings",
+  selfCheck: "mcpp.selfCheck",
+} as const;
+
+/**
+ * Ids kept for compatibility. A keybinding or a script that names one of these
+ * still works; the menu shows the new title.
+ */
+export const DEPRECATED_COMMANDS = {
+  configureClangd: "mcpp.configureClangd",
+} as const;
+
+export type CommandId =
+  | (typeof CLI_COMMANDS)[keyof typeof CLI_COMMANDS]
+  | (typeof LEGACY_LANGUAGE_SERVER_COMMANDS)[keyof typeof LEGACY_LANGUAGE_SERVER_COMMANDS]
+  | (typeof LANGUAGE_SERVER_COMMANDS)[keyof typeof LANGUAGE_SERVER_COMMANDS]
+  | (typeof CACHE_COMMANDS)[keyof typeof CACHE_COMMANDS]
+  | (typeof LIBRARY_COMMANDS)[keyof typeof LIBRARY_COMMANDS]
+  | (typeof TOOL_COMMANDS)[keyof typeof TOOL_COMMANDS];
+
+/** Every id the manifest contributes, in the order the palette shows them. */
+export function contributedCommandIds(): string[] {
+  return [
+    ...Object.values(TOOL_COMMANDS),
+    ...Object.values(CLI_COMMANDS),
+    ...Object.values(CACHE_COMMANDS),
+    ...Object.values(LIBRARY_COMMANDS),
+    ...Object.values(LANGUAGE_SERVER_COMMANDS),
+    ...Object.values(LEGACY_LANGUAGE_SERVER_COMMANDS),
+    ...Object.values(DEPRECATED_COMMANDS),
+  ];
+}
diff --git a/src/commands/menu.ts b/src/commands/menu.ts
new file mode 100644
index 0000000..342690e
--- /dev/null
+++ b/src/commands/menu.ts
@@ -0,0 +1,103 @@
+import { CACHE_COMMANDS, CLI_COMMANDS, LANGUAGE_SERVER_COMMANDS, LIBRARY_COMMANDS, TOOL_COMMANDS } from "./ids";
+
+/**
+ * The status-bar menu, as **data**: entries are keyed by command id, the titles
+ * are resolved through `src/i18n/t.ts` when the menu is built, and the icon is a
+ * codicon id without the `$()` (the same convention `TreeNode.icon` uses).
+ *
+ * The groups are not decoration. They are what the menu is built from — the
+ * quick pick renders one separator per group — so an entry and its section can
+ * never disagree, and a section that ends up empty simply produces no separator.
+ *
+ * ## Why the icons are files
+ *
+ * `vscode.QuickPickItem.iconPath` accepts a `ThemeIcon`, but VS Code 1.132
+ * discards its colour: `MainThreadQuickOpen.expandIconPath` turns the icon into a
+ * bare codicon class (`o.iconClass = asClassName(e)`), and the list renderer only
+ * ever paints that class in the row's ordinary foreground. A `Uri` is different —
+ * it becomes the row's `background-image`, painted as-is — so the only way to
+ * colour a quick pick icon is to *ship a coloured image*.
+ *
+ * That is what `iconColor` is for. It is a **palette word** (`blue`, `green`, …),
+ * not a theme-colour id like `TreeNode.iconColor`, because the colour is baked
+ * into the file and cannot follow the theme the way a `ThemeIcon` does. Each word
+ * resolves to the default light and dark value of the matching `charts.*` token,
+ * so the menu and the project tree agree; `media/quick-menu/----
+ * .svg` is generated from `@vscode/codicons` by
+ * `tools/generate-quick-menu-icons.mjs`, and `test/commands/menu.test.ts` walks
+ * this table and stats every file so the two cannot drift apart.
+ *
+ * The palette groups rows by **what they do**, the same way the tree does: blue
+ * builds or adds, green runs or verifies, purple tests or collects, yellow
+ * manages the toolchain, red deletes, and `neutral` is for rows whose only job is
+ * to configure or report.
+ */
+export interface QuickMenuItem {
+  labelKey: string;
+  command: string;
+  /** A codicon id, e.g. `"tools"`. */
+  icon: string;
+  /** A palette word; see the note above. */
+  iconColor: QuickMenuColour;
+  group: "project" | "library" | "toolchain" | "cache" | "languageServer" | "settings";
+}
+
+/** The palette words `iconColor` may use; the generator owns their values. */
+export const QUICK_MENU_COLOURS = ["blue", "green", "purple", "yellow", "red", "neutral"] as const;
+
+export type QuickMenuColour = (typeof QUICK_MENU_COLOURS)[number];
+
+/** The groups, in the order the menu shows them. */
+export const QUICK_MENU_GROUPS: ReadonlyArray<{ id: QuickMenuItem["group"]; labelKey: string }> = [
+  { id: "project", labelKey: "Current mcpp project" },
+  { id: "library", labelKey: "mcpp library ecosystem" },
+  { id: "toolchain", labelKey: "mcpp toolchain management" },
+  { id: "cache", labelKey: "Build cache" },
+  { id: "languageServer", labelKey: "C++ Modules language service" },
+  { id: "settings", labelKey: "Settings and diagnostics" },
+];
+
+/**
+ * The asset name for one row's icon in one theme.
+ *
+ * The generator writes exactly these names; the test checks that every one of
+ * them exists, which is what keeps this convention and the files in step.
+ */
+export function quickMenuIconAsset(item: QuickMenuItem, theme: "dark" | "light"): string {
+  return `${item.icon}--${item.iconColor}--${theme}.svg`;
+}
+
+export const quickMenuItems: readonly QuickMenuItem[] = [
+  { labelKey: "Build", command: CLI_COMMANDS.build, icon: "tools", iconColor: "blue", group: "project" },
+  { labelKey: "Run", command: CLI_COMMANDS.run, icon: "play", iconColor: "green", group: "project" },
+  { labelKey: "Test", command: CLI_COMMANDS.test, icon: "beaker", iconColor: "purple", group: "project" },
+  { labelKey: "Clean project artifacts", command: CACHE_COMMANDS.cleanProject, icon: "trash", iconColor: "red", group: "project" },
+
+  { labelKey: "Search and add a dependency", command: LIBRARY_COMMANDS.search, icon: "library", iconColor: "blue", group: "library" },
+  { labelKey: "Refresh the mcpp Package Index", command: LIBRARY_COMMANDS.updateIndex, icon: "cloud-download", iconColor: "blue", group: "library" },
+
+  { labelKey: "Show toolchains", command: CLI_COMMANDS.showToolchains, icon: "chip", iconColor: "yellow", group: "toolchain" },
+  { labelKey: "Install toolchain", command: CLI_COMMANDS.installToolchain, icon: "cloud-download", iconColor: "yellow", group: "toolchain" },
+  { labelKey: "Select the global default toolchain", command: CLI_COMMANDS.selectDefaultToolchain, icon: "star-full", iconColor: "yellow", group: "toolchain" },
+
+  { labelKey: "Refresh cache statistics", command: CACHE_COMMANDS.refreshStats, icon: "refresh", iconColor: "green", group: "cache" },
+  { labelKey: "Clean stale artifacts", command: CACHE_COMMANDS.cleanStale, icon: "trash", iconColor: "red", group: "cache" },
+  { labelKey: "Collect the global cache to a budget", command: CACHE_COMMANDS.collect, icon: "archive", iconColor: "purple", group: "cache" },
+  { labelKey: "Verify the shared cache", command: CACHE_COMMANDS.verify, icon: "verified", iconColor: "green", group: "cache" },
+
+  { labelKey: "C++ Modules: restart the language server", command: LANGUAGE_SERVER_COMMANDS.restart, icon: "debug-restart", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: select the analysis context", command: LANGUAGE_SERVER_COMMANDS.selectContext, icon: "symbol-interface", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: show the module graph", command: LANGUAGE_SERVER_COMMANDS.showModuleGraph, icon: "type-hierarchy", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: open the log", command: LANGUAGE_SERVER_COMMANDS.showLogs, icon: "output", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: capture the logs (report + bundle)", command: LANGUAGE_SERVER_COMMANDS.exportDiagnosticBundle, icon: "file-zip", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: show the diagnostic report", command: LANGUAGE_SERVER_COMMANDS.collectReport, icon: "report", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: open the log folder", command: LANGUAGE_SERVER_COMMANDS.openLogFolder, icon: "folder-opened", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: show the last captured bundle", command: LANGUAGE_SERVER_COMMANDS.revealBundle, icon: "folder", iconColor: "neutral", group: "languageServer" },
+  { labelKey: "C++ Modules: reset this workspace's cache", command: LANGUAGE_SERVER_COMMANDS.resetWorkspaceCache, icon: "trash", iconColor: "neutral", group: "languageServer" },
+
+  { labelKey: "Build and refresh the language service", command: CLI_COMMANDS.autoConfigureModules, icon: "refresh", iconColor: "blue", group: "settings" },
+  { labelKey: "Environment self-check", command: TOOL_COMMANDS.selfCheck, icon: "heart", iconColor: "green", group: "settings" },
+  { labelKey: "mcpp settings", command: TOOL_COMMANDS.openSettings, icon: "settings-gear", iconColor: "neutral", group: "settings" },
+];
+
+export const quickMenuStatusText = "$(tools) mcpp";
diff --git a/src/config/access.ts b/src/config/access.ts
new file mode 100644
index 0000000..862e465
--- /dev/null
+++ b/src/config/access.ts
@@ -0,0 +1,133 @@
+/**
+ * Typed reads and writes for `mcpp.*` settings.
+ *
+ * Every read goes through the registry, so a value that does not match its
+ * declaration (a hand-edited `settings.json`) is replaced by the declared
+ * default and reported once — never silently passed on to the rest of the code.
+ *
+ * Writes always name a target. The configuration panel and the commands choose
+ * it deliberately; nothing here writes `mcppls.*` or any other section.
+ */
+
+import * as vscode from "vscode";
+
+import { defaultValue, expectation, validateValue } from "./validate";
+import { SECTION, SETTINGS, setting, subKey, type SettingEntry } from "./registry";
+
+export type ValueSource = "default" | "user" | "workspace" | "workspaceFolder" | "language" | "invalid";
+
+export interface EffectiveValue {
+  value: T;
+  source: ValueSource;
+}
+
+const warned = new Set();
+
+function configuration(resource?: vscode.Uri): vscode.WorkspaceConfiguration {
+  return vscode.workspace.getConfiguration(SECTION, resource ?? null);
+}
+
+/**
+ * Where the effective value comes from, for the panel's "current value" column
+ * and for the environment self-check.
+ */
+export function effective(key: string, resource?: vscode.Uri): EffectiveValue {
+  const entry = setting(key);
+  if (entry === undefined) {
+    return { value: undefined as unknown as T, source: "invalid" };
+  }
+  const inspected = configuration(resource).inspect(entry.key.slice(SECTION.length + 1));
+  const candidates: Array<[ValueSource, unknown]> = [
+    ["workspaceFolder", inspected?.workspaceFolderValue],
+    ["workspace", inspected?.workspaceValue],
+    ["user", inspected?.globalValue],
+  ];
+  for (const [source, raw] of candidates) {
+    if (raw === undefined) {
+      continue;
+    }
+    const result = validateValue(entry, raw);
+    if (result.ok) {
+      return { value: result.value as T, source };
+    }
+    warnOnce(entry, source, raw);
+    return { value: defaultValue(entry), source: "invalid" };
+  }
+  return { value: defaultValue(entry), source: "default" };
+}
+
+/** Shorthand for callers that only want the value. */
+export function read(key: string, resource?: vscode.Uri): T {
+  return effective(key, resource).value;
+}
+
+function warnOnce(entry: SettingEntry, source: ValueSource, raw: unknown): void {
+  const signature = `${entry.key}@${source}`;
+  if (warned.has(signature)) {
+    return;
+  }
+  warned.add(signature);
+  void vscode.window.showWarningMessage(
+    `${entry.key}: ${JSON.stringify(raw)} is not a valid value (expected ${expectation(entry)}); using the default.`,
+  );
+}
+
+/** Test seam: forget which invalid values have been reported. */
+export function resetInvalidWarnings(): void {
+  warned.clear();
+}
+
+export type WriteTarget = "user" | "workspace" | "workspaceFolder";
+
+function configurationTarget(target: WriteTarget): vscode.ConfigurationTarget {
+  switch (target) {
+    case "workspace":
+      return vscode.ConfigurationTarget.Workspace;
+    case "workspaceFolder":
+      return vscode.ConfigurationTarget.WorkspaceFolder;
+    default:
+      return vscode.ConfigurationTarget.Global;
+  }
+}
+
+/**
+ * Write one setting. A `resource`-scoped setting must name the folder it
+ * applies to, otherwise VS Code would write it to the wrong place.
+ */
+export async function write(
+  key: string,
+  value: unknown,
+  target: WriteTarget,
+  resource?: vscode.Uri,
+): Promise {
+  const entry = setting(key);
+  if (entry === undefined) {
+    throw new Error(`unknown mcpp setting: ${key}`);
+  }
+  if (entry.scope === "resource" && target !== "user" && resource === undefined) {
+    throw new Error(`${key} is resource-scoped; a folder URI is required`);
+  }
+  await configuration(resource).update(subKey(entry.key), value, configurationTarget(target));
+}
+
+/** Every setting whose effective value differs from its declared default. */
+export function changedSettings(resource?: vscode.Uri): Array<{ key: string; value: unknown; source: ValueSource }> {
+  const changed: Array<{ key: string; value: unknown; source: ValueSource }> = [];
+  for (const entry of SETTINGS) {
+    const current = effective(entry.key, resource);
+    if (current.source === "default" || current.source === "language") {
+      continue;
+    }
+    changed.push({ key: entry.key, value: current.value, source: current.source });
+  }
+  return changed;
+}
+
+/** Fires for any `mcpp.*` change; the panel and the views subscribe once. */
+export function onDidChange(listener: () => void): vscode.Disposable {
+  return vscode.workspace.onDidChangeConfiguration((event) => {
+    if (event.affectsConfiguration(SECTION)) {
+      listener();
+    }
+  });
+}
diff --git a/src/config/migrate.ts b/src/config/migrate.ts
new file mode 100644
index 0000000..053fd34
--- /dev/null
+++ b/src/config/migrate.ts
@@ -0,0 +1,66 @@
+/**
+ * Renamed settings: the old name keeps working, and the user is offered the
+ * move once.
+ *
+ * This mirrors what the C++ Modules extension does for its own renames: read
+ * the alias, write nothing until the user agrees, and never remove the old
+ * value on their behalf.
+ */
+
+import * as vscode from "vscode";
+
+import { effective, write } from "./access";
+import { renamedKeys, subKey, SECTION } from "./registry";
+
+export interface RenamedSetting {
+  from: string;
+  to: string;
+  value: unknown;
+}
+
+/** Renames whose old name still holds a value the new name does not. */
+export function pendingRenames(resource?: vscode.Uri): RenamedSetting[] {
+  const pending: RenamedSetting[] = [];
+  const configuration = vscode.workspace.getConfiguration(SECTION, resource ?? null);
+  for (const { from, to } of renamedKeys()) {
+    const oldValue = configuration.get(subKey(from));
+    if (oldValue === undefined) {
+      continue;
+    }
+    const current = effective(to, resource);
+    if (current.source !== "default") {
+      continue;
+    }
+    pending.push({ from, to, value: oldValue });
+  }
+  return pending;
+}
+
+/**
+ * Perform the move for every pending rename. The old key is left in place —
+ * removing a user's setting is their decision, and a stale alias is harmless
+ * because nothing reads it.
+ */
+export async function applyRenames(
+  pending: readonly RenamedSetting[],
+  target: "user" | "workspace",
+  resource?: vscode.Uri,
+): Promise {
+  let moved = 0;
+  for (const rename of pending) {
+    try {
+      await write(rename.to, rename.value, target, resource);
+      moved += 1;
+    } catch {
+      // A rejected write (read-only settings, no folder) is not fatal: the user
+      // can still set the new key themselves.
+    }
+  }
+  return moved;
+}
+
+/** Notification text, kept here so the panel and the activation path agree. */
+export function renamePrompt(pending: readonly RenamedSetting[]): string {
+  const names = pending.map((rename) => `${rename.from} → ${rename.to}`).join(", ");
+  return `mcpp: ${pending.length} setting(s) were renamed (${names}). Move them to the new names?`;
+}
diff --git a/src/config/panel.ts b/src/config/panel.ts
new file mode 100644
index 0000000..86eeb9e
--- /dev/null
+++ b/src/config/panel.ts
@@ -0,0 +1,403 @@
+/**
+ * The VS Code half of the configuration panel: `mcpp: Open the settings panel`.
+ *
+ * The panel is deliberately narrow. It is a **reading aid** for the 60+ settings
+ * in `data/config-registry.json`: it groups them, shows each one's effective
+ * value and where that value comes from, and explains when a change takes
+ * effect. It does not replace the Settings editor — every row has a link that
+ * opens the native one — and it names the boundary out loud: it writes
+ * `mcpp.*` only, never `mcppls.*`, which belongs to the C++ Modules extension.
+ *
+ * Safety rules this file is responsible for:
+ *
+ * - a key is written only if the registry declares it (so `mcpp.*` only);
+ * - a value is validated against the registry before it is written, so the
+ *   panel cannot be the thing that puts a bad value in `settings.json`;
+ * - a `resource`-scoped setting is never written to a workspace level without a
+ *   folder URI (VS Code has nowhere to put it);
+ * - a rejected write (a read-only level, a folder that went away) is swallowed:
+ *   the panel re-sends the effective model, and the user sees the real state.
+ *
+ * `src/config/panelHtml.ts` owns the document; this module owns the data and the
+ * messages. The webview answers every action with `{ type: "model", model }`.
+ */
+
+import * as path from "node:path";
+import * as vscode from "vscode";
+
+import { TOOL_COMMANDS } from "../commands/ids";
+import { languagePreference, t } from "../i18n/t";
+import { localeFromEditorLanguage } from "../i18n/translate";
+import { MCPPLS_EXTENSION_ID } from "../mcppls/contract";
+import { WebviewDocument } from "../webview/document";
+import { effective, onDidChange, write, type WriteTarget } from "./access";
+import {
+  PANEL_UI,
+  decodePanelMessage,
+  renderPanelHtml,
+  type PanelModel,
+  type PanelPreset,
+  type PanelRow,
+  type PanelSection,
+} from "./panelHtml";
+import { PRESETS, presetValues } from "./presets";
+import { GROUPS, SECTION, SETTINGS, setting, settingsInGroup, subKey, type SettingEntry } from "./registry";
+import { validateValue } from "./validate";
+
+/** `@ext:` queries need `publisher.name`, which is not in any registry. */
+const EXTENSION_ID = "mcpp-community.mcpp-vscode";
+const PANEL_VIEW_TYPE = "mcpp.settingsPanel";
+const OPEN_SETTINGS = "workbench.action.openSettings";
+const MEDIA_DIRECTORY = "media";
+const STYLESHEET = "settings.css";
+
+/**
+ * The slice of `vscode.ExtensionContext` this module needs. `extensionUri` is
+ * optional so the declared shape stays callable from tests and from hosts that
+ * do not have one; when it is missing the media directory is derived from
+ * `__dirname` (`dist/src/config/` → the extension root).
+ */
+export interface PanelHostContext {
+  subscriptions: { push(...items: unknown[]): unknown };
+  extensionUri?: vscode.Uri;
+}
+
+interface PanelSession {
+  panel: vscode.WebviewPanel;
+  resource?: vscode.Uri;
+  host: PanelHostContext;
+  /**
+   * The document and its per-panel nonce. The panel's html is assigned exactly
+   * once per open — every later update travels by `postMessage` — but the kit
+   * is still used so every webview host in this extension holds its document
+   * the same way (one nonce minting point, one assignment site).
+   */
+  webviewDocument: WebviewDocument;
+}
+
+/** One panel per window: reopening reveals and refreshes the existing one. */
+let session: PanelSession | undefined;
+
+/**
+ * Register `mcpp.openSettings`. The command takes no arguments; the panel's
+ * resource (the folder whose values it shows) follows the active editor when it
+ * is inside a workspace folder, otherwise the first folder.
+ */
+export function registerSettingsPanel(host: PanelHostContext): void {
+  host.subscriptions.push(
+    vscode.commands.registerCommand(TOOL_COMMANDS.openSettings, () => {
+      open(host);
+    }),
+    onDidChange(() => {
+      if (session !== undefined) {
+        postModel(session);
+      }
+    }),
+    {
+      dispose: () => {
+        session?.panel.dispose();
+        session = undefined;
+      },
+    },
+  );
+}
+
+function open(host: PanelHostContext): void {
+  if (session !== undefined) {
+    session.panel.reveal();
+    postModel(session);
+    return;
+  }
+  const resource = resourceUri();
+  const panel = vscode.window.createWebviewPanel(PANEL_VIEW_TYPE, t("mcpp settings"), vscode.ViewColumn.Active, {
+    enableScripts: true,
+    localResourceRoots: [mediaRoot(host)],
+    retainContextWhenHidden: false,
+  });
+  const active: PanelSession = { panel, resource, host, webviewDocument: new WebviewDocument(STYLESHEET) };
+  session = active;
+  const model = buildModel(resource);
+  const html = renderPanelHtml(model, {
+    ...active.webviewDocument.assets(mediaRoot(host), panel.webview),
+    // The client script is inline and nonced; the CSP names no external script
+    // source, so this stays empty on purpose.
+    scriptUri: "",
+  });
+  active.webviewDocument.paint(panel.webview, html);
+  panel.webview.onDidReceiveMessage((raw: unknown) => {
+    void handle(active, raw);
+  });
+  panel.onDidDispose(() => {
+    if (session === active) {
+      session = undefined;
+    }
+  });
+}
+
+async function handle(active: PanelSession, raw: unknown): Promise {
+  const message = decodePanelMessage(raw);
+  if (message === undefined) {
+    return;
+  }
+  try {
+    switch (message.type) {
+      case "update":
+        await applyUpdate(active, message.key, message.value, message.target);
+        break;
+      case "reset":
+        await resetEverywhere(message.key, active.resource);
+        break;
+      case "preset":
+        await applyPreset(message.id, active.resource);
+        break;
+      case "openNative":
+        await vscode.commands.executeCommand(OPEN_SETTINGS, `@ext:${EXTENSION_ID} ${message.key}`);
+        break;
+      case "openMcpplsSettings":
+        await vscode.commands.executeCommand(OPEN_SETTINGS, `@ext:${MCPPLS_EXTENSION_ID}`);
+        break;
+    }
+  } catch {
+    // A write can fail for reasons that are the user's business, not the
+    // panel's: a read-only settings level, a folder that disappeared. The model
+    // sent below shows the value that is actually in effect.
+  }
+  postModel(active);
+}
+
+async function applyUpdate(
+  active: PanelSession,
+  key: string,
+  value: unknown,
+  target: "user" | "workspace",
+): Promise {
+  const entry = setting(key);
+  if (entry === undefined) {
+    return;
+  }
+  const validated = validateValue(entry, value);
+  if (!validated.ok || !writable(entry, target, active.resource)) {
+    return;
+  }
+  await write(entry.key, validated.value, target, active.resource);
+}
+
+/** A resource-scoped setting needs a folder URI for any workspace-level write. */
+function writable(entry: SettingEntry, target: WriteTarget, resource?: vscode.Uri): boolean {
+  return !(entry.scope === "resource" && target !== "user" && resource === undefined);
+}
+
+function configurationTarget(target: WriteTarget): vscode.ConfigurationTarget {
+  switch (target) {
+    case "workspace":
+      return vscode.ConfigurationTarget.Workspace;
+    case "workspaceFolder":
+      return vscode.ConfigurationTarget.WorkspaceFolder;
+    default:
+      return vscode.ConfigurationTarget.Global;
+  }
+}
+
+/**
+ * Remove one level's override. `configuration.update(key, undefined, target)` is
+ * the only way to delete a value; leaving the level alone is not enough, because
+ * a workspace value would then keep shadowing the default.
+ */
+async function resetKey(key: string, target: WriteTarget, resource?: vscode.Uri): Promise {
+  const entry = setting(key);
+  if (entry === undefined || !writable(entry, target, resource)) {
+    return;
+  }
+  await vscode.workspace
+    .getConfiguration(SECTION, resource ?? null)
+    .update(subKey(key), undefined, configurationTarget(target));
+}
+
+/** "Reset" means "back to the default", so every level that could hold it is cleared. */
+async function resetEverywhere(key: string, resource?: vscode.Uri): Promise {
+  const targets: WriteTarget[] =
+    resource === undefined ? ["user", "workspace"] : ["user", "workspace", "workspaceFolder"];
+  for (const target of targets) {
+    try {
+      await resetKey(key, target, resource);
+    } catch {
+      // An unwritable level is skipped; the others still get cleared.
+    }
+  }
+}
+
+async function applyPreset(id: string, resource?: vscode.Uri): Promise {
+  // `defaults` carries no values by design; it is the one preset that resets.
+  if (id === "defaults") {
+    for (const entry of SETTINGS) {
+      await resetEverywhere(entry.key, resource);
+    }
+    return;
+  }
+  const target: WriteTarget = resource === undefined ? "user" : "workspace";
+  for (const { key, value } of presetValues(id)) {
+    const entry = setting(key);
+    if (entry === undefined || !writable(entry, target, resource)) {
+      continue;
+    }
+    const validated = validateValue(entry, value);
+    if (!validated.ok) {
+      continue;
+    }
+    try {
+      await write(entry.key, validated.value, target, resource);
+    } catch {
+      // Keep applying the rest of the preset rather than stopping halfway.
+    }
+  }
+}
+
+/**
+ * The whole model. Labels go through `t()`, so the panel follows the editor's
+ * language exactly like the runtime messages do; registry titles and
+ * descriptions are the same English strings `package.nls.*` carries, and fall
+ * back to English until their translations land in `data/i18n`.
+ */
+function buildModel(resource?: vscode.Uri): PanelModel {
+  const sections: PanelSection[] = GROUPS.map((group) => ({
+    id: group.id,
+    title: t(group.title),
+    rows: settingsInGroup(group.id).map((entry) => buildRow(entry, resource)),
+  })).filter((section) => section.rows.length > 0);
+  const presets: PanelPreset[] = PRESETS.map((preset) => ({
+    id: preset.id,
+    title: t(preset.title),
+    description: t(preset.description),
+  }));
+  const model: PanelModel = { sections, presets, ui: panelLabels() };
+  const label = resource === undefined ? undefined : folderLabel(resource);
+  if (label !== undefined) {
+    model.resourceLabel = label;
+  }
+  return model;
+}
+
+function buildRow(entry: SettingEntry, resource?: vscode.Uri): PanelRow {
+  const current = effective(entry.key, resource);
+  const row: PanelRow = {
+    key: entry.key,
+    title: t(entry.title),
+    description: t(entry.description),
+    type: entry.type,
+    value: current.value,
+    scope: entry.scope,
+    applies: entry.applies,
+    // `effective()` also reports `language`, which is a level, not a source the
+    // panel can show a button for; it reads as a plain user-level value.
+    source: current.source === "language" ? "default" : current.source,
+    tier: entry.tier,
+    since: entry.since,
+  };
+  if (entry.enum !== undefined) {
+    // Enum values are identifiers (`auto`, `workspaceFolder`, `warning`); the
+    // registry has no separate label for them and inventing copy here would
+    // give the panel words the Settings editor does not use.
+    row.options = entry.enum.map((value) => ({ value, label: value }));
+  }
+  if (entry.minimum !== undefined) {
+    row.minimum = entry.minimum;
+  }
+  if (entry.maximum !== undefined) {
+    row.maximum = entry.maximum;
+  }
+  if (entry.deprecated === true) {
+    row.deprecated = true;
+    if (entry.deprecationMessage !== undefined) {
+      row.deprecationMessage = t(entry.deprecationMessage);
+    }
+  }
+  return row;
+}
+
+/**
+ * Every visible string, resolved once per model. These are the literals
+ * `tools/l10n-check.mjs` holds to `data/i18n/zh-cn.json`.
+ */
+function panelLabels(): Record {
+  return {
+    [PANEL_UI.htmlLang]: htmlLanguage(),
+    [PANEL_UI.title]: t("mcpp settings"),
+    [PANEL_UI.boundary]: t(
+      "This panel changes mcpp-vscode settings only; the C++ Modules extension ({0}) keeps its own mcppls.* settings and this panel never writes them.",
+      MCPPLS_EXTENSION_ID,
+    ),
+    [PANEL_UI.openMcpplsSettings]: t("Open the C++ Modules settings"),
+    [PANEL_UI.resourceLabel]: t("Values shown for {0}"),
+    [PANEL_UI.search]: t("Search settings"),
+    [PANEL_UI.onlyModified]: t("Only modified"),
+    [PANEL_UI.showAdvanced]: t("Show advanced settings"),
+    [PANEL_UI.target]: t("Save settings to"),
+    [PANEL_UI.targetUser]: t("User settings"),
+    [PANEL_UI.targetWorkspace]: t("Workspace settings"),
+    [PANEL_UI.targetWorkspaceUnavailable]: t("No workspace folder is open"),
+    [PANEL_UI.presets]: t("Presets"),
+    [PANEL_UI.modified]: t("Changed from the default"),
+    [PANEL_UI.deprecated]: t("Deprecated"),
+    [PANEL_UI.invalid]: t("Invalid"),
+    [PANEL_UI.appliesNextBuild]: t("Takes effect on the next build"),
+    [PANEL_UI.appliesNextClean]: t("Takes effect on the next clean"),
+    [PANEL_UI.appliesViewReload]: t("Reload the window to see this"),
+    [PANEL_UI.sourceDefault]: t("Default"),
+    [PANEL_UI.sourceUser]: t("User"),
+    [PANEL_UI.sourceWorkspace]: t("Workspace"),
+    [PANEL_UI.sourceWorkspaceFolder]: t("Workspace folder"),
+    [PANEL_UI.sourceInvalid]: t("Invalid"),
+    [PANEL_UI.reset]: t("Reset"),
+    [PANEL_UI.resetInvalid]: t("Reset the invalid value to the default"),
+    [PANEL_UI.openNative]: t("Open in the Settings editor"),
+    [PANEL_UI.arrayHint]: t("One value per line"),
+    [PANEL_UI.noMatches]: t("No settings match the search"),
+    [PANEL_UI.toggleSection]: t("Toggle this section"),
+  };
+}
+
+/** `auto` is the editor's own language; `en`/`zh-cn` are the manual override. */
+function htmlLanguage(): string {
+  const preference = languagePreference();
+  if (preference === "zh-cn") {
+    return "zh-cn";
+  }
+  if (preference === "en") {
+    return "en";
+  }
+  return localeFromEditorLanguage(vscode.env.language) === "zh-cn" ? "zh-cn" : "en";
+}
+
+function postModel(active: PanelSession): void {
+  void active.panel.webview.postMessage({ type: "model", model: buildModel(active.resource) });
+}
+
+/**
+ * The folder whose values the panel shows. An active editor inside a workspace
+ * folder wins (that is the project the user is looking at); otherwise the first
+ * folder. `undefined` means "no resource", and then only user-level writes are
+ * offered.
+ */
+function resourceUri(): vscode.Uri | undefined {
+  const active = vscode.window.activeTextEditor?.document.uri;
+  if (active !== undefined) {
+    const folder = vscode.workspace.getWorkspaceFolder(active);
+    if (folder !== undefined) {
+      return folder.uri;
+    }
+  }
+  return vscode.workspace.workspaceFolders?.[0]?.uri;
+}
+
+function folderLabel(resource: vscode.Uri): string {
+  return vscode.workspace.getWorkspaceFolder(resource)?.name ?? path.basename(resource.fsPath);
+}
+
+function mediaRoot(host: PanelHostContext): vscode.Uri {
+  const extensionUri = host.extensionUri ?? vscode.extensions.getExtension(EXTENSION_ID)?.extensionUri;
+  if (extensionUri !== undefined) {
+    return vscode.Uri.joinPath(extensionUri, MEDIA_DIRECTORY);
+  }
+  // `dist/src/config/` -> the extension root, where `media/` ships.
+  return vscode.Uri.file(path.join(__dirname, "..", "..", "..", MEDIA_DIRECTORY));
+}
diff --git a/src/config/panelHtml.ts b/src/config/panelHtml.ts
new file mode 100644
index 0000000..7af7456
--- /dev/null
+++ b/src/config/panelHtml.ts
@@ -0,0 +1,612 @@
+/**
+ * The configuration panel's document, as a pure function.
+ *
+ * Everything the panel shows is data: `src/config/panel.ts` resolves the
+ * registry and the current values into a `PanelModel`, and this module turns
+ * that into one self-contained HTML document. No `vscode`, no file system, no
+ * network — which is what makes the interesting parts (escaping, the strict
+ * CSP, the advanced/deprecated/invalid marking) unit-testable.
+ *
+ * House rules the tests pin down:
+ *
+ * - **Strict CSP.** `default-src 'none'` plus exactly three sources: the
+ *   stylesheet, the nonced inline script, and the webview's own image source.
+ *   There are no external resources and no inline `style=` attributes, so a
+ *   theme change cannot be the only thing that makes a control usable.
+ * - **No hard-coded copy.** Every user-visible label is looked up in
+ *   `PanelModel.ui`, which the caller has already localized; the renderer never
+ *   invents English. A key the caller forgot degrades to the key itself rather
+ *   than to a blank control.
+ * - **No unescaped interpolation.** Every value from the registry or from
+ *   `settings.json` goes through `escapeHtml`; the client script only ever
+ *   assigns through `textContent`, never `innerHTML`.
+ * - **State is text plus shape, not colour.** Source, deprecation and invalid
+ *   state are rendered as labelled badges and hidden attributes; the stylesheet
+ *   adds borders around them. Colour is decoration only, so high-contrast
+ *   themes stay readable.
+ *
+ * The webview talks back with JSON `postMessage`s (see `decodePanelMessage`)
+ * and the host answers with `{ type: "model", model }`, which the client script
+ * applies in place.
+ */
+
+import { format } from "../i18n/translate";
+
+/** One choice of an enum setting. */
+export interface PanelOption {
+  value: string;
+  label: string;
+}
+
+/** One setting, ready to render. Values and copy are already resolved. */
+export interface PanelRow {
+  key: string;
+  title: string;
+  description: string;
+  type: "boolean" | "string" | "number" | "array";
+  value: boolean | string | number | string[];
+  options?: PanelOption[];
+  minimum?: number;
+  maximum?: number;
+  scope: "resource" | "window";
+  applies: "immediate" | "next-build" | "next-clean" | "view-reload";
+  source: "default" | "user" | "workspace" | "workspaceFolder" | "invalid";
+  tier: "public" | "advanced";
+  deprecated?: boolean;
+  deprecationMessage?: string;
+  since: string;
+}
+
+/** One registry group, with its rows in registry order. */
+export interface PanelSection {
+  id: string;
+  title: string;
+  rows: PanelRow[];
+}
+
+/** One preset button. */
+export interface PanelPreset {
+  id: string;
+  title: string;
+  description: string;
+}
+
+export interface PanelModel {
+  sections: PanelSection[];
+  presets: PanelPreset[];
+  /** Every label the panel shows, already localized by the caller. */
+  ui: Record;
+  /** The workspace folder the values belong to, when the panel was opened from one. */
+  resourceLabel?: string;
+}
+
+export interface PanelAssets {
+  cspSource: string;
+  nonce: string;
+  styleUri: string;
+  scriptUri: string;
+}
+
+/**
+ * The `ui` keys the renderer reads, so the caller and the renderer cannot drift
+ * apart on a string. `panel.ts` fills all of them through `t()`.
+ */
+export const PANEL_UI = {
+  htmlLang: "panel.htmlLang",
+  title: "panel.title",
+  boundary: "panel.boundary",
+  openMcpplsSettings: "panel.openMcpplsSettings",
+  resourceLabel: "panel.resourceLabel",
+  search: "panel.search",
+  onlyModified: "panel.onlyModified",
+  showAdvanced: "panel.showAdvanced",
+  target: "panel.target",
+  targetUser: "panel.target.user",
+  targetWorkspace: "panel.target.workspace",
+  targetWorkspaceUnavailable: "panel.target.workspaceUnavailable",
+  presets: "panel.presets",
+  modified: "panel.modified",
+  deprecated: "panel.deprecated",
+  invalid: "panel.invalid",
+  appliesNextBuild: "panel.applies.nextBuild",
+  appliesNextClean: "panel.applies.nextClean",
+  appliesViewReload: "panel.applies.viewReload",
+  sourceDefault: "panel.source.default",
+  sourceUser: "panel.source.user",
+  sourceWorkspace: "panel.source.workspace",
+  sourceWorkspaceFolder: "panel.source.workspaceFolder",
+  sourceInvalid: "panel.source.invalid",
+  reset: "panel.reset",
+  resetInvalid: "panel.resetInvalid",
+  openNative: "panel.openNative",
+  arrayHint: "panel.arrayHint",
+  noMatches: "panel.noMatches",
+  toggleSection: "panel.toggleSection",
+} as const;
+
+const SOURCE_UI: Record = {
+  default: PANEL_UI.sourceDefault,
+  user: PANEL_UI.sourceUser,
+  workspace: PANEL_UI.sourceWorkspace,
+  workspaceFolder: PANEL_UI.sourceWorkspaceFolder,
+  invalid: PANEL_UI.sourceInvalid,
+};
+
+const APPLIES_UI: Partial> = {
+  "next-build": PANEL_UI.appliesNextBuild,
+  "next-clean": PANEL_UI.appliesNextClean,
+  "view-reload": PANEL_UI.appliesViewReload,
+};
+
+export type PanelUiLabel = (key: string) => string;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(//g, ">")
+    .replace(/"/g, """)
+    .replace(/'/g, "'");
+}
+
+/**
+ * The CSP is an attribute value, but its single quotes are syntax: escaping
+ * them would turn `'none'` into `'none'` and make the document state a
+ * different policy than it means. Only the characters that could end the
+ * attribute or start a tag are escaped; `cspSource` and the nonce come from
+ * VS Code and from `crypto`, not from the registry.
+ */
+function escapeCsp(value: string): string {
+  return value.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """);
+}
+
+/** ` name="value"`, or nothing when the value is absent. */
+function attribute(name: string, value: string | number | undefined): string {
+  return value === undefined ? "" : ` ${name}="${escapeHtml(String(value))}"`;
+}
+
+/** ` name`, or nothing. Boolean HTML attributes only. */
+function flag(name: string, on: boolean): string {
+  return on ? ` ${name}` : "";
+}
+
+/** The text of the `applies` hint, or `""` when the setting is immediate. */
+function appliesHint(row: PanelRow, label: PanelUiLabel): string {
+  const key = APPLIES_UI[row.applies];
+  return key === undefined ? "" : label(key);
+}
+
+function renderControl(row: PanelRow, label: PanelUiLabel): string {
+  const invalid = row.source === "invalid";
+  const key = escapeHtml(row.key);
+  const aria = escapeHtml(row.title);
+  if (row.type === "boolean") {
+    return (
+      ``
+    );
+  }
+  if (row.type === "number") {
+    return (
+      ``
+    );
+  }
+  if (row.type === "array") {
+    const lines = Array.isArray(row.value) ? row.value.join("\n") : String(row.value);
+    return (
+      `${escapeHtml(lines)}` +
+      `${escapeHtml(label(PANEL_UI.arrayHint))}`
+    );
+  }
+  if (row.options !== undefined && row.options.length > 0) {
+    const options = row.options
+      .map(
+        (option) =>
+          ``,
+      )
+      .join("");
+    return (
+      ``
+    );
+  }
+  return (
+    ``
+  );
+}
+
+function renderRow(row: PanelRow, label: PanelUiLabel): string {
+  const invalid = row.source === "invalid";
+  const modified = row.source !== "default";
+  const deprecated = row.deprecated === true;
+  const deprecation = row.deprecationMessage ?? "";
+  const hint = appliesHint(row, label);
+  const advanced = row.tier === "advanced";
+  const resetTitle = invalid ? label(PANEL_UI.resetInvalid) : label(PANEL_UI.reset);
+  return [
+    ``,
+    `  `,
+    `    ${escapeHtml(row.title)}`,
+    `    ${escapeHtml(label(PANEL_UI.modified))}`,
+    `    ${escapeHtml(label(PANEL_UI.deprecated))}`,
+    `    ${escapeHtml(label(PANEL_UI.invalid))}`,
+    `    ${escapeHtml(label(SOURCE_UI[row.source]))}`,
+    `  `,
+    `  ${escapeHtml(row.description)}`,
+    `  ${escapeHtml(deprecation)}`,
+    `  ${escapeHtml(hint)}`,
+    `  ${renderControl(row, label)}`,
+    `  `,
+    `    `,
+    `    `,
+    `  `,
+    ``,
+  ].join("\n");
+}
+
+function renderSection(section: PanelSection, label: PanelUiLabel): string {
+  const rows = section.rows.map((row) => renderRow(row, label)).join("\n");
+  return [
+    ``,
+    `  `,
+    `    `,
+    `  `,
+    `  `,
+    rows,
+    `  `,
+    ``,
+  ].join("\n");
+}
+
+function renderPresets(presets: readonly PanelPreset[], label: PanelUiLabel): string {
+  if (presets.length === 0) {
+    return "";
+  }
+  const buttons = presets
+    .map(
+      (preset) =>
+        ``,
+    )
+    .join("\n    ");
+  return [
+    ``,
+    `  ${escapeHtml(label(PANEL_UI.presets))}`,
+    `  `,
+    `    ${buttons}`,
+    `  `,
+    ``,
+  ].join("\n");
+}
+
+function renderToolbar(label: PanelUiLabel, hasResource: boolean): string {
+  return [
+    ``,
+    `  `,
+    `  ${escapeHtml(label(PANEL_UI.onlyModified))}`,
+    `  ${escapeHtml(label(PANEL_UI.showAdvanced))}`,
+    `  ${escapeHtml(label(PANEL_UI.target))}`,
+    `    `,
+    `  `,
+    ``,
+  ].join("\n");
+}
+
+/**
+ * A model embedded in the page's own script. `<` is escaped so a registry
+ * string (or a value from `settings.json`) can never close the script element.
+ */
+function embedJson(value: unknown): string {
+  return JSON.stringify(value)
+    .replace(/ 0; });
+    }
+    return element.value;
+  }
+
+  function writeControl(element, row) {
+    var kind = element.getAttribute("data-kind");
+    if (kind === "boolean") { element.checked = row.value === true; }
+    else if (kind === "array") { element.value = (row.value || []).join("\\n"); }
+    else { element.value = row.value === undefined || row.value === null ? "" : String(row.value); }
+    element.disabled = row.source === "invalid";
+  }
+
+  function applyRow(row) {
+    var element = rowElements[row.key];
+    if (!element) { return; }
+    element.setAttribute("data-source", row.source);
+    element.setAttribute("data-modified", row.source === "default" ? "false" : "true");
+    setText(element.querySelector('[data-badge="source"]'), ui[SOURCE_KEYS[row.source]] || row.source);
+    setHidden(element.querySelector('[data-badge="modified"]'), row.source === "default");
+    setHidden(element.querySelector('[data-badge="deprecated"]'), row.deprecated !== true);
+    setHidden(element.querySelector('[data-badge="invalid"]'), row.source !== "invalid");
+    var deprecation = element.querySelector(".row-deprecation");
+    var message = typeof row.deprecationMessage === "string" ? row.deprecationMessage : "";
+    setText(deprecation, message);
+    setHidden(deprecation, message.length === 0);
+    var applies = element.querySelector(".row-applies");
+    var appliesKey = APPLIES_KEYS[row.applies];
+    var hint = appliesKey ? (ui[appliesKey] || "") : "";
+    setText(applies, hint);
+    setHidden(applies, hint.length === 0);
+    var input = element.querySelector("[data-control]");
+    if (input) { writeControl(input, row); }
+  }
+
+  function rowVisible(key, element, query, onlyChanged, advanced) {
+    if (!advanced && element.getAttribute("data-tier") === "advanced") { return false; }
+    if (onlyChanged && element.getAttribute("data-modified") !== "true") { return false; }
+    if (query.length === 0) { return true; }
+    var title = element.querySelector(".row-title");
+    var description = element.querySelector(".row-description");
+    var haystack = key + " " + (title ? title.textContent : "") + " " + (description ? description.textContent : "");
+    return haystack.toLowerCase().indexOf(query) >= 0;
+  }
+
+  function filter() {
+    var query = searchInput ? searchInput.value.trim().toLowerCase() : "";
+    var onlyChanged = onlyModifiedInput ? onlyModifiedInput.checked : false;
+    var advanced = showAdvancedInput ? showAdvancedInput.checked : false;
+    var anySection = false;
+    for (var index = 0; index < sectionElements.length; index += 1) {
+      var section = sectionElements[index];
+      var rows = section.querySelectorAll("[data-row]");
+      var anyRow = false;
+      for (var inner = 0; inner < rows.length; inner += 1) {
+        var element = rows[inner];
+        var shown = rowVisible(element.getAttribute("data-row"), element, query, onlyChanged, advanced);
+        element.hidden = !shown;
+        if (shown) { anyRow = true; }
+      }
+      section.hidden = !anyRow;
+      if (anyRow) { anySection = true; }
+    }
+    if (emptyState) { emptyState.hidden = anySection; }
+  }
+
+  function applyModel(next) {
+    if (!next) { return; }
+    state = next;
+    ui = next.ui || {};
+    var sections = next.sections || [];
+    for (var index = 0; index < sections.length; index += 1) {
+      var rows = sections[index].rows || [];
+      for (var inner = 0; inner < rows.length; inner += 1) { applyRow(rows[inner]); }
+    }
+    var presets = next.presets || [];
+    for (var presetIndex = 0; presetIndex < presets.length; presetIndex += 1) {
+      var button = presetElements[presets[presetIndex].id];
+      if (button) {
+        setText(button, presets[presetIndex].title);
+        if (typeof presets[presetIndex].description === "string") { button.title = presets[presetIndex].description; }
+      }
+    }
+    filter();
+  }
+
+  if (searchInput) { searchInput.addEventListener("input", filter); }
+  if (onlyModifiedInput) { onlyModifiedInput.addEventListener("change", filter); }
+  if (showAdvancedInput) { showAdvancedInput.addEventListener("change", filter); }
+
+  document.addEventListener("change", function (event) {
+    var element = event.target;
+    if (!element || typeof element.getAttribute !== "function") { return; }
+    if (!element.hasAttribute("data-control")) { return; }
+    var row = element.closest("[data-row]");
+    if (!row) { return; }
+    var value = readControl(element);
+    if (value === undefined) { return; }
+    post({ type: "update", key: row.getAttribute("data-row"), value: value, target: targetSelect ? targetSelect.value : "user" });
+  });
+
+  document.addEventListener("click", function (event) {
+    var target = event.target;
+    if (!target || typeof target.closest !== "function") { return; }
+    var button = target.closest("button");
+    if (!button) { return; }
+    var preset = button.getAttribute("data-preset");
+    if (preset) { post({ type: "preset", id: preset }); return; }
+    if (button.hasAttribute("data-section-toggle")) {
+      var section = button.closest("[data-section]");
+      if (section) {
+        var collapsed = section.getAttribute("data-collapsed") === "true";
+        section.setAttribute("data-collapsed", collapsed ? "false" : "true");
+        button.setAttribute("aria-expanded", collapsed ? "true" : "false");
+      }
+      return;
+    }
+    var action = button.getAttribute("data-action");
+    if (action === "reset" || action === "openNative") {
+      var row = button.closest("[data-row]");
+      if (row) {
+        if (action === "reset") { post({ type: "reset", key: row.getAttribute("data-row") }); }
+        else { post({ type: "openNative", key: row.getAttribute("data-row") }); }
+      }
+      return;
+    }
+    if (button.id === "panel-open-mcppls") { post({ type: "openMcpplsSettings" }); }
+  });
+
+  window.addEventListener("message", function (event) {
+    var data = event.data;
+    if (data && data.type === "model" && data.model) { applyModel(data.model); }
+  });
+
+  filter();
+  post({ type: "ready" });
+})();`;
+}
+
+/**
+ * The whole document. `assets.scriptUri` is accepted for the contract but not
+ * used: the client script is inline and nonced, and the CSP names no external
+ * script source, so nothing else can be loaded.
+ */
+export function renderPanelHtml(model: PanelModel, assets: PanelAssets): string {
+  const label: PanelUiLabel = (key) => model.ui[key] ?? key;
+  const hasResource = model.resourceLabel !== undefined;
+  const sections = model.sections.map((section) => renderSection(section, label)).join("\n");
+  const lang = model.ui[PANEL_UI.htmlLang] ?? "";
+  const resource =
+    model.resourceLabel === undefined
+      ? ""
+      : `${escapeHtml(format(label(PANEL_UI.resourceLabel), [model.resourceLabel]))}`;
+  const csp = `default-src 'none'; style-src ${assets.cspSource}; script-src 'nonce-${assets.nonce}'; img-src ${assets.cspSource}`;
+  return `
+
+
+
+
+
+
+${escapeHtml(label(PANEL_UI.title))}
+
+
+
+  ${escapeHtml(label(PANEL_UI.title))}
+  ${escapeHtml(label(PANEL_UI.boundary))} 
+  ${resource}
+
+${renderToolbar(label, hasResource)}
+${renderPresets(model.presets, label)}
+
+${sections}
+
+${escapeHtml(label(PANEL_UI.noMatches))}
+
+
+
+`;
+}
+
+/** Values posted back by the webview, decoded and validated. */
+export type PanelMessage =
+  | { type: "update"; key: string; value: unknown; target: "user" | "workspace" }
+  | { type: "reset"; key: string }
+  | { type: "preset"; id: string }
+  | { type: "openNative"; key: string }
+  | { type: "openMcpplsSettings" }
+  | { type: "ready" };
+
+function isRecord(value: unknown): value is Record {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * Decode one `postMessage` payload. Webview input is untrusted: anything that
+ * is not exactly one of the six shapes is dropped, and the returned object is
+ * rebuilt so foreign fields never travel further.
+ *
+ * A settings key is always required and always non-empty; `update` additionally
+ * needs a write target and a `value` field (the value itself may be anything —
+ * `validate.ts` checks it against the registry before it is written).
+ */
+export function decodePanelMessage(raw: unknown): PanelMessage | undefined {
+  if (!isRecord(raw)) {
+    return undefined;
+  }
+  switch (raw.type) {
+    case "ready":
+      return { type: "ready" };
+    case "openMcpplsSettings":
+      return { type: "openMcpplsSettings" };
+    case "update": {
+      if (!nonEmptyString(raw.key) || !("value" in raw)) {
+        return undefined;
+      }
+      if (raw.target !== "user" && raw.target !== "workspace") {
+        return undefined;
+      }
+      return { type: "update", key: raw.key, value: raw.value, target: raw.target };
+    }
+    case "reset":
+      return nonEmptyString(raw.key) ? { type: "reset", key: raw.key } : undefined;
+    case "preset":
+      return nonEmptyString(raw.id) ? { type: "preset", id: raw.id } : undefined;
+    case "openNative":
+      return nonEmptyString(raw.key) ? { type: "openNative", key: raw.key } : undefined;
+    default:
+      return undefined;
+  }
+}
diff --git a/src/config/presets.ts b/src/config/presets.ts
new file mode 100644
index 0000000..21d3b2e
--- /dev/null
+++ b/src/config/presets.ts
@@ -0,0 +1,110 @@
+/**
+ * Named bundles of setting values for the configuration panel.
+ *
+ * Pure: a preset is data, so the panel, the tests and the docs all read the same
+ * table. A preset only ever names keys that exist in the registry (enforced by
+ * `presetProblems()` and the unit tests) — a preset that silently does nothing is
+ * worse than no preset.
+ */
+
+import { setting } from "./registry";
+
+export interface Preset {
+  id: string;
+  /** English; the panel localizes this through `src/i18n/t.ts`. */
+  title: string;
+  description: string;
+  /** Key -> value, applied in order. */
+  values: Readonly>;
+}
+
+export const PRESETS: readonly Preset[] = [
+  {
+    id: "defaults",
+    title: "Defaults",
+    description: "Put every mcpp setting back to its shipped default.",
+    values: {},
+  },
+  {
+    id: "quiet",
+    title: "Quiet",
+    description: "No status-bar counters, no automatic refresh, no editor diagnostics from this extension.",
+    values: {
+      "mcpp.cache.statusBar": false,
+      "mcpp.cache.autoRefreshSeconds": 0,
+      "mcpp.languageService.stateRefreshSeconds": 0,
+      "mcpp.ui.notifications.success": "silent",
+      "mcpp.task.focusTerminal": false,
+      "mcpp.toml.diagnostics.unknownKey": "off",
+      "mcpp.toml.diagnostics.legacyKeys": "off",
+      "mcpp.buildScript.diagnostics": false,
+    },
+  },
+  {
+    id: "everything",
+    title: "Everything on",
+    description: "All observation and editing help enabled, including the ones that run mcpp a little more often.",
+    values: {
+      "mcpp.cache.statusBar": true,
+      "mcpp.cache.autoRefreshSeconds": 60,
+      "mcpp.cache.warnAboveGiB": 10,
+      "mcpp.languageService.readState": true,
+      "mcpp.languageService.stateRefreshSeconds": 30,
+      "mcpp.languageService.notifyOnDegraded": true,
+      "mcpp.toml.hover": true,
+      "mcpp.toml.navigation": true,
+      "mcpp.toml.diagnostics.enabled": true,
+      "mcpp.toml.diagnostics.unknownSection": "warning",
+      "mcpp.toml.diagnostics.unknownKey": "warning",
+      "mcpp.toml.diagnostics.planeSeparation": "warning",
+      "mcpp.toml.diagnostics.legacyKeys": "info",
+      "mcpp.buildScript.intelligence": true,
+      "mcpp.buildScript.diagnostics": true,
+      "mcpp.buildScript.snippets": true,
+      "mcpp.buildScript.imports.knownModules": true,
+      "mcpp.views.cache.topN": 10,
+      "mcpp.ui.notifications.success": "statusBar",
+      "mcpp.log.level": "info",
+    },
+  },
+  {
+    id: "diagnose",
+    title: "Diagnose",
+    description: "Turn the logging up and read the C++ Modules state, for when something is wrong.",
+    values: {
+      "mcpp.log.level": "debug",
+      "mcpp.languageService.readState": true,
+      "mcpp.languageService.stateRefreshSeconds": 15,
+      "mcpp.languageService.notifyOnDegraded": true,
+      "mcpp.diagnostics.selfCheckOnStartup": true,
+      "mcpp.toml.diagnostics.unknownSection": "warning",
+      "mcpp.toml.diagnostics.unknownKey": "warning",
+    },
+  },
+];
+
+export function preset(id: string): Preset | undefined {
+  return PRESETS.find((entry) => entry.id === id);
+}
+
+/** The key/value pairs a preset would write. `defaults` writes nothing: see `resetKeys()`. */
+export function presetValues(id: string): Array<{ key: string; value: unknown }> {
+  const found = preset(id);
+  if (found === undefined) {
+    return [];
+  }
+  return Object.entries(found.values).map(([key, value]) => ({ key, value }));
+}
+
+/** Registry keys a preset mentions that do not exist (must be empty). */
+export function presetProblems(): string[] {
+  const problems: string[] = [];
+  for (const entry of PRESETS) {
+    for (const key of Object.keys(entry.values)) {
+      if (setting(key) === undefined) {
+        problems.push(`preset ${entry.id} names unknown setting ${key}`);
+      }
+    }
+  }
+  return problems;
+}
diff --git a/src/config/registry.ts b/src/config/registry.ts
new file mode 100644
index 0000000..2f73423
--- /dev/null
+++ b/src/config/registry.ts
@@ -0,0 +1,184 @@
+/**
+ * The settings registry: **the single source of truth** for everything this
+ * extension makes configurable.
+ *
+ * `data/config-registry.json` holds the declaration; `package.json`'s
+ * `contributes.configuration` is hand-written but held to it by
+ * `tools/check-config.mjs`, and `docs/settings.md` is generated from it. The
+ * configuration panel (`src/config/panel.ts`) renders it, and
+ * `mcpp: environment self-check` dumps the entries the user has changed.
+ *
+ * Shape rules are enforced by `tools/check-config.mjs` and by the unit tests:
+ * unique keys, every `group` present in `groups`, ascending `order` within a
+ * group, and a `default` that `validate.ts` accepts.
+ */
+
+import registryJson from "../../data/config-registry.json";
+
+export type SettingType = "boolean" | "string" | "number" | "array";
+export type SettingScope = "resource" | "window";
+export type SettingTier = "public" | "advanced";
+export type SettingApplies = "immediate" | "next-build" | "next-clean" | "view-reload";
+
+export interface SettingEntry {
+  key: string;
+  type: SettingType;
+  default: boolean | string | number | string[];
+  enum?: string[];
+  minimum?: number;
+  maximum?: number;
+  scope: SettingScope;
+  group: string;
+  order: number;
+  tier: SettingTier;
+  applies: SettingApplies;
+  since: string;
+  deprecated?: boolean;
+  aliases?: string[];
+  title: string;
+  description: string;
+  deprecationMessage?: string;
+}
+
+export interface SettingGroup {
+  id: string;
+  order: number;
+  title: string;
+}
+
+interface RegistryFile {
+  version: number;
+  groups: SettingGroup[];
+  settings: SettingEntry[];
+}
+
+const registry = registryJson as unknown as RegistryFile;
+
+export const SETTINGS: readonly SettingEntry[] = registry.settings;
+export const GROUPS: readonly SettingGroup[] = [...registry.groups].sort((a, b) => a.order - b.order);
+
+const BY_KEY = new Map(SETTINGS.map((entry) => [entry.key, entry]));
+const GROUP_BY_ID = new Map(GROUPS.map((group) => [group.id, group]));
+
+/** The section every key lives under; VS Code's `getConfiguration` needs it. */
+export const SECTION = "mcpp";
+
+/** `"mcpp.cache.staleDays"` -> `"cache.staleDays"`. */
+export function subKey(key: string): string {
+  return key.startsWith(`${SECTION}.`) ? key.slice(SECTION.length + 1) : key;
+}
+
+export function setting(key: string): SettingEntry | undefined {
+  return BY_KEY.get(key);
+}
+
+export function requireSetting(key: string): SettingEntry {
+  const entry = BY_KEY.get(key);
+  if (entry === undefined) {
+    throw new Error(`unknown mcpp setting: ${key}`);
+  }
+  return entry;
+}
+
+export function groupOf(key: string): SettingGroup | undefined {
+  const entry = BY_KEY.get(key);
+  return entry === undefined ? undefined : GROUP_BY_ID.get(entry.group);
+}
+
+/** Entries of one group, in their declared order. */
+export function settingsInGroup(groupId: string): SettingEntry[] {
+  return SETTINGS.filter((entry) => entry.group === groupId)
+    .slice()
+    .sort((a, b) => a.order - b.order);
+}
+
+export function settingsByTier(tier: SettingTier): SettingEntry[] {
+  return SETTINGS.filter((entry) => entry.tier === tier);
+}
+
+/** Keys this build mentions in the manifest, in registry order. */
+export function manifestKeys(): string[] {
+  return SETTINGS.map((entry) => entry.key);
+}
+
+/** The key an old name now resolves to, or `undefined` when it is unknown. */
+export function aliasedKey(oldKey: string): string | undefined {
+  for (const entry of SETTINGS) {
+    if (entry.aliases?.includes(oldKey) === true) {
+      return entry.key;
+    }
+  }
+  return undefined;
+}
+
+/** Old name -> current name, for the one-time migration prompt. */
+export function renamedKeys(): Array<{ from: string; to: string }> {
+  const pairs: Array<{ from: string; to: string }> = [];
+  for (const entry of SETTINGS) {
+    for (const alias of entry.aliases ?? []) {
+      pairs.push({ from: alias, to: entry.key });
+    }
+  }
+  return pairs;
+}
+
+/**
+ * The registry's own invariants. Returns a list of problems (empty when sound).
+ *
+ * The same rules live in `tools/check-config.mjs`, but having them here means a
+ * malformed `data/config-registry.json` is caught by the unit tests as well —
+ * and lets `activate()` log a single line instead of failing feature by feature.
+ */
+export function registryShapeProblems(): string[] {
+  const problems: string[] = [];
+  const groupIds = new Set();
+  for (const group of GROUPS) {
+    if (groupIds.has(group.id)) {
+      problems.push(`duplicate group ${group.id}`);
+    }
+    groupIds.add(group.id);
+    if (typeof group.title !== "string" || group.title.length === 0) {
+      problems.push(`group ${group.id} has no title`);
+    }
+  }
+  const seen = new Set();
+  const lastOrder = new Map();
+  for (const entry of SETTINGS) {
+    if (!entry.key.startsWith(`${SECTION}.`)) {
+      problems.push(`${entry.key} is not a ${SECTION}.* key`);
+    }
+    if (seen.has(entry.key)) {
+      problems.push(`duplicate key ${entry.key}`);
+    }
+    seen.add(entry.key);
+    if (!groupIds.has(entry.group)) {
+      problems.push(`${entry.key} names undeclared group ${entry.group}`);
+    }
+    const previous = lastOrder.get(entry.group);
+    if (previous !== undefined && !(entry.order > previous)) {
+      problems.push(`${entry.group} order is not ascending at ${entry.key}`);
+    }
+    lastOrder.set(entry.group, entry.order);
+    if (entry.title.length === 0 || entry.description.length === 0) {
+      problems.push(`${entry.key} has an empty title or description`);
+    }
+    if (entry.enum !== undefined && !entry.enum.includes(entry.default as string)) {
+      problems.push(`${entry.key} default is not in its enum`);
+    }
+    if (entry.deprecated === true && entry.deprecationMessage === undefined) {
+      problems.push(`${entry.key} is deprecated without a deprecationMessage`);
+    }
+  }
+  return problems;
+}
+
+/** Every setting key, ordered by group then by the group's own order. */
+export function groupedKeys(): string[] {
+  const keys: string[] = [];
+  for (const group of GROUPS) {
+    for (const entry of settingsInGroup(group.id)) {
+      keys.push(entry.key);
+    }
+  }
+  return keys;
+}
diff --git a/src/config/validate.ts b/src/config/validate.ts
new file mode 100644
index 0000000..91ec337
--- /dev/null
+++ b/src/config/validate.ts
@@ -0,0 +1,93 @@
+/**
+ * Value validation for the settings registry. Pure: no `vscode`.
+ *
+ * Used in two places: `access.ts` when a value arrives from the editor (a
+ * hand-edited `settings.json` can hold anything), and the configuration panel
+ * before it writes. An invalid value never reaches the rest of the extension –
+ * the declared default is used and the user is told once.
+ */
+
+import type { SettingEntry } from "./registry";
+
+export type ValidationFailure =
+  | "type"
+  | "enum"
+  | "minimum"
+  | "maximum"
+  | "items";
+
+export interface ValidationResult {
+  ok: boolean;
+  /** Present when `ok`: the coerced value. */
+  value?: boolean | string | number | string[];
+  /** Present when `!ok`: why it was rejected. */
+  reason?: ValidationFailure;
+}
+
+function typeOf(entry: SettingEntry): string {
+  return entry.type === "array" ? "array of strings" : entry.type;
+}
+
+export function validateValue(entry: SettingEntry, raw: unknown): ValidationResult {
+  if (raw === undefined || raw === null) {
+    return { ok: false, reason: "type" };
+  }
+  switch (entry.type) {
+    case "boolean": {
+      if (typeof raw !== "boolean") {
+        return { ok: false, reason: "type" };
+      }
+      return { ok: true, value: raw };
+    }
+    case "number": {
+      if (typeof raw !== "number" || !Number.isFinite(raw)) {
+        return { ok: false, reason: "type" };
+      }
+      if (entry.minimum !== undefined && raw < entry.minimum) {
+        return { ok: false, reason: "minimum" };
+      }
+      if (entry.maximum !== undefined && raw > entry.maximum) {
+        return { ok: false, reason: "maximum" };
+      }
+      return { ok: true, value: raw };
+    }
+    case "string": {
+      if (typeof raw !== "string") {
+        return { ok: false, reason: "type" };
+      }
+      if (entry.enum !== undefined && !entry.enum.includes(raw)) {
+        return { ok: false, reason: "enum" };
+      }
+      return { ok: true, value: raw };
+    }
+    case "array": {
+      if (!Array.isArray(raw)) {
+        return { ok: false, reason: "type" };
+      }
+      if (raw.some((item) => typeof item !== "string")) {
+        return { ok: false, reason: "items" };
+      }
+      return { ok: true, value: [...raw] as string[] };
+    }
+    default:
+      return { ok: false, reason: "type" };
+  }
+}
+
+/** The declared default, as a fresh value (arrays are copied). */
+export function defaultValue(entry: SettingEntry): T {
+  return (Array.isArray(entry.default) ? [...entry.default] : entry.default) as T;
+}
+
+/** Human-readable expectation, for the "value rejected" notice. */
+export function expectation(entry: SettingEntry): string {
+  if (entry.enum !== undefined) {
+    return entry.enum.join(" | ");
+  }
+  if (entry.type === "number" && (entry.minimum !== undefined || entry.maximum !== undefined)) {
+    const low = entry.minimum ?? Number.NEGATIVE_INFINITY;
+    const high = entry.maximum ?? Number.POSITIVE_INFINITY;
+    return `${low} … ${high}`;
+  }
+  return typeOf(entry);
+}
diff --git a/src/configureOnly.ts b/src/configureOnly.ts
deleted file mode 100644
index cf233ae..0000000
--- a/src/configureOnly.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { runProcess, type ProcessResult, type ProcessRunner } from "./process";
-
-export const configureOnlyArguments = ["build", "--configure-only"] as const;
-// 配置阶段可能解析工具链和依赖，但不能无限期占住 IDE 操作队列。
-export const configureOnlyTimeoutMs = 5 * 60_000;
-
-export function runConfigureOnly(
-  projectRoot: string,
-  executable = "mcpp",
-  runner: ProcessRunner = runProcess,
-): Promise {
-  return runner(
-    executable,
-    [...configureOnlyArguments],
-    projectRoot,
-    { timeoutMs: configureOnlyTimeoutMs },
-  );
-}
diff --git a/src/extension.ts b/src/extension.ts
index b4d875e..db251be 100644
--- a/src/extension.ts
+++ b/src/extension.ts
@@ -1,23 +1,73 @@
 import * as vscode from "vscode";
 
-import { McppCliController } from "./cliController";
-import { CLI_COMMANDS, DEPRECATED_COMMANDS } from "./commands";
-import { findNearestMcppProject, type McppProjectDiscovery } from "./discovery";
-import { MCPP_MANIFEST_GLOB, registerInProjectContext } from "./inProject";
+import { McppCliController, discoveryBoundaryFromSettings } from "./cli/controller";
+import { runMcpp } from "./cli/process";
+import { parseProtocolInfo } from "./cli/protocol";
+import { buildSelfCheckText } from "./cli/selfCheck";
+import { CLI_COMMANDS, LEGACY_LANGUAGE_SERVER_COMMANDS, LIBRARY_COMMANDS, TOOL_COMMANDS } from "./commands/ids";
+import { findNearestMcppProject, type McppProjectDiscovery } from "./projects/discovery";
+import { MCPP_MANIFEST_GLOB, registerInProjectContext } from "./projects/context";
 import {
   createLanguageServerBridge,
   type LanguageServerBridge,
   type LanguageServerCommandResult,
-} from "./languageServer";
-import { computeMcppTomlCompletions } from "./mcppTomlCompletion";
+} from "./mcppls/bridge";
+import { compareVersions } from "./library/xpkg";
+import { CAPABILITIES, MCPPLS_EXTENSION_ID, VERIFIED_MCPPLS_MINIMUM, VERIFIED_MCPPLS_RANGE } from "./mcppls/contract";
+import { formatResult } from "./mcppls/messages";
+import { describeState } from "./mcppls/state";
+import {
+  languageServerEnabled,
+  languageServerInstalled,
+  languageServerVersion,
+  readLanguageServerState,
+} from "./mcppls/stateSource";
+import { registerBuildScriptProviders } from "./buildscript/providers";
+import { registerTomlProviders } from "./toml/providers";
 import {
   buildModuleSetupPlan,
   executeModuleSetup,
   moduleSetupConfirmation,
   type ModuleSetupDecision,
   type ModuleSetupStepResult,
-} from "./moduleSetup";
-import type { TaskCompletion } from "./tasks";
+} from "./workflows/moduleSetup";
+import type { TaskCompletion } from "./cli/tasks";
+import { changedSettings, onDidChange as onConfigurationChanged, read } from "./config/access";
+import { applyRenames, pendingRenames, renamePrompt } from "./config/migrate";
+import { registerSettingsPanel } from "./config/panel";
+import { languagePreference, setLanguagePreference, t, type LanguagePreference } from "./i18n/t";
+import { readCacheSnapshot, registerCacheView } from "./cache/cacheView";
+import { registerLanguageServerCommands } from "./views/languageServerView";
+import { createLibraryDetailOpener } from "./library/detailPanel";
+import { loadSnapshot } from "./library/indexLocator";
+import { registerLibraryView } from "./library/libraryView";
+import { registerProjectView } from "./views/projectView";
+
+/**
+ * The commands an extension declares in its own `package.json`, read without
+ * activating it. `undefined` means "no static information", which the capability
+ * probe treats as "assume it works until a call says otherwise".
+ */
+function declaredCommandsOf(id: string): readonly string[] | undefined {
+  const extension = vscode.extensions.getExtension(id);
+  const commands = (extension?.packageJSON as { contributes?: { commands?: Array<{ command?: string }> } })
+    ?.contributes?.commands;
+  if (!Array.isArray(commands)) {
+    return undefined;
+  }
+  return commands
+    .map((entry) => entry.command)
+    .filter((command): command is string => typeof command === "string");
+}
+
+/** When the language service was last asked to reload, for the self-check. */
+let lastRefresh: { at: string; state: string; command?: string } | undefined;
+
+/** `mcpp.ui.language` decides which of our strings the user sees. */
+function applyLanguagePreference(): void {
+  setLanguagePreference(read("mcpp.ui.language"));
+}
+
 
 function findCurrentProject(): McppProjectDiscovery | undefined {
   const activeEditor = vscode.window.activeTextEditor;
@@ -30,11 +80,19 @@ function findCurrentProject(): McppProjectDiscovery | undefined {
     if (workspaceFolder === undefined) {
       return undefined;
     }
-    return findNearestMcppProject(activeUri.fsPath, workspaceFolder.uri.fsPath);
+    return findNearestMcppProject(
+      activeUri.fsPath,
+      workspaceFolder.uri.fsPath,
+      discoveryBoundaryFromSettings(workspaceFolder.uri),
+    );
   }
 
   for (const workspaceFolder of vscode.workspace.workspaceFolders ?? []) {
-    const project = findNearestMcppProject(workspaceFolder.uri.fsPath);
+    const project = findNearestMcppProject(
+      workspaceFolder.uri.fsPath,
+      workspaceFolder.uri.fsPath,
+      discoveryBoundaryFromSettings(workspaceFolder.uri),
+    );
     if (project !== undefined) {
       return project;
     }
@@ -51,35 +109,41 @@ function outputText(output: vscode.OutputChannel, line: string): void {
 }
 
 function resultText(output: vscode.OutputChannel, result: LanguageServerCommandResult): void {
-  outputText(output, `[C++ Modules] ${result.message}`);
+  const formatted = formatResult(result);
+  outputText(output, `[C++ Modules] ${formatted.message}${formatted.hint === undefined ? "" : ` ${formatted.hint}`}`);
   if (result.state === "unavailable") {
-    void vscode.window.showWarningMessage(result.message, "安装扩展").then((choice) => {
-      if (choice === "安装扩展") {
-        void vscode.commands.executeCommand("workbench.extensions.search", "@id:sunrisepeak.mcpp-language-server");
+    const install = t("Install extension");
+    void vscode.window.showWarningMessage(formatted.message, install).then((choice) => {
+      if (choice === install) {
+        void vscode.commands.executeCommand("workbench.extensions.search", `@id:${MCPPLS_EXTENSION_ID}`);
       }
     });
-  } else if (result.state === "failed") {
-    void vscode.window.showErrorMessage(result.message);
+    return;
+  }
+  if (formatted.severity === "warning") {
+    void vscode.window.showWarningMessage(formatted.message);
+  } else if (formatted.severity === "error") {
+    void vscode.window.showErrorMessage(formatted.message);
   }
 }
 
 function moduleSetupBlockedMessage(reason: Extract["reason"]): string {
   switch (reason) {
     case "untrusted":
-      return "当前工作区未受信任，不会执行 mcpp 或刷新 C++ 模块语言服务。请先信任工作区。";
+      return t("This workspace is not trusted, so mcpp will not run and the C++ Modules language service will not refresh. Trust the workspace first.");
     case "busy":
-      return "已有 mcpp 操作正在运行，请等待完成后再试。";
+      return t("An mcpp operation is already running; wait for it to finish and try again.");
   }
 }
 
 function taskCompletionText(completion: TaskCompletion): string {
   if (completion.state === "cancelled") {
-    return "构建已取消；C++ 模块语言服务未刷新。";
+    return t("The build was cancelled; the C++ Modules language service was not refreshed.");
   }
   if (completion.state === "failed") {
-    return `mcpp 构建失败（退出码 ${completion.exitCode ?? "未知"}）；C++ 模块语言服务已重新读取现有构建描述。`;
+    return t("The mcpp build failed (exit code {0}); the C++ Modules language service re-read the existing build description.", completion.exitCode ?? t("unknown"));
   }
-  return "mcpp 构建完成，C++ 模块语言服务已刷新。";
+  return t("The mcpp build finished; the C++ Modules language service has been refreshed.");
 }
 
 async function autoConfigureModulesWizard(
@@ -102,12 +166,14 @@ async function autoConfigureModulesWizard(
     return;
   }
   const confirmation = moduleSetupConfirmation();
+  // One definition: the label is shown *and* the reply is compared against it.
+  const confirmLabel = t("Confirm one-click setup");
   const choice = await vscode.window.showWarningMessage(
     confirmation.message,
     { modal: true, detail: confirmation.detail },
-    "确认一键配置",
+    confirmLabel,
   );
-  if (choice !== "确认一键配置") {
+  if (choice !== confirmLabel) {
     return;
   }
 
@@ -118,7 +184,7 @@ async function autoConfigureModulesWizard(
         return {
           stage: "build",
           state: "not-started",
-          detail: "未启动 mcpp 构建。",
+          detail: t("mcpp build was not started."),
         };
       }
       return {
@@ -133,7 +199,7 @@ async function autoConfigureModulesWizard(
       return {
         stage: "language-server",
         state: result.state === "completed" ? "succeeded" : "failed",
-        detail: result.state === "completed" ? undefined : result.message,
+        detail: result.state === "completed" ? undefined : formatResult(result).message,
       };
     },
   });
@@ -146,53 +212,20 @@ async function autoConfigureModulesWizard(
   } else if (outcome.state === "cancelled") {
     await vscode.window.showWarningMessage(taskCompletionText({ state: "cancelled" }));
   } else {
-    await vscode.window.showErrorMessage(outcome.steps.at(-1)?.detail ?? "C++ 模块语言服务配置失败。");
+    await vscode.window.showErrorMessage(outcome.steps.at(-1)?.detail ?? t("Configuring the C++ Modules language service failed."));
   }
 }
 
-// mcpp.toml structural completion is deliberately local text analysis. It never executes mcpp or
-// the language server, so it remains available in restricted workspaces.
-const mcppTomlCompletionKinds = {
-  section: vscode.CompletionItemKind.Folder,
-  template: vscode.CompletionItemKind.Snippet,
-} as const;
-
-const mcppTomlCompletionProvider: vscode.CompletionItemProvider = {
-  provideCompletionItems(document, position) {
-    if (!vscode.workspace.getConfiguration("mcpp", document.uri).get("tomlCompletion", true)) {
-      return undefined;
-    }
-    const lines: string[] = [];
-    for (let line = 0; line <= position.line; line += 1) {
-      lines.push(document.lineAt(line).text);
-    }
-    return computeMcppTomlCompletions(lines, position.line, position.character).map((suggestion) => {
-      const item = new vscode.CompletionItem(
-        suggestion.label,
-        mcppTomlCompletionKinds[suggestion.kind],
-      );
-      item.detail = suggestion.detail;
-      if (suggestion.documentation !== undefined) {
-        item.documentation = new vscode.MarkdownString(suggestion.documentation);
-      }
-      if (suggestion.insertSnippet !== undefined) {
-        item.insertText = new vscode.SnippetString(suggestion.insertSnippet);
-      }
-      item.range = new vscode.Range(
-        position.line,
-        suggestion.range.startCharacter,
-        position.line,
-        suggestion.range.endCharacter,
-      );
-      return item;
-    });
-  },
-};
-
 export async function activate(extensionContext: vscode.ExtensionContext): Promise {
   const output = vscode.window.createOutputChannel("mcpp");
+
+  // Language first: everything below may want to speak to the user.
+  applyLanguagePreference();
+  extensionContext.subscriptions.push(onConfigurationChanged(applyLanguagePreference));
+
   const bridge = createLanguageServerBridge({
     extensionInstalled: (id) => vscode.extensions.getExtension(id) !== undefined,
+    declaredCommands: declaredCommandsOf,
     activateExtension: async (id) => {
       await vscode.extensions.getExtension(id)?.activate();
     },
@@ -203,8 +236,8 @@ export async function activate(extensionContext: vscode.ExtensionContext): Promi
       await operation();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      outputText(output, `发生未预期错误：${message}`);
-      void vscode.window.showErrorMessage(`mcpp：${message}`);
+      outputText(output, t("Unexpected error: {0}", message));
+      void vscode.window.showErrorMessage(t("mcpp: {0}", message));
     }
   };
   const invokeLanguageServer = (
@@ -233,7 +266,14 @@ export async function activate(extensionContext: vscode.ExtensionContext): Promi
     if (completion.state === "cancelled") {
       return;
     }
-    const result = await bridge.refreshLanguageServerAfterBuild();
+    const mode = read("mcpp.languageService.refreshAfterBuild");
+    if (mode === "off") {
+      lastRefresh = { at: new Date().toISOString(), state: "skipped (mcpp.languageService.refreshAfterBuild = off)" };
+      return;
+    }
+    const result =
+      mode === "restart" ? await bridge.restartLanguageServer() : await bridge.refreshLanguageServerAfterBuild();
+    lastRefresh = { at: new Date().toISOString(), state: result.state, command: result.command };
     resultText(output, result);
     if (completion.state === "succeeded" && result.state === "completed") {
       await vscode.window.showInformationMessage(taskCompletionText(completion));
@@ -244,9 +284,145 @@ export async function activate(extensionContext: vscode.ExtensionContext): Promi
 
   const cliController = new McppCliController({
     output,
+    extensionUri: extensionContext.extensionUri,
     currentProject: findCurrentProject,
     afterProjectTask,
     isTrusted: () => vscode.workspace.isTrusted,
+    languageServerSummary: () => {
+      const view = readLanguageServerState();
+      return view.available ? view.state : undefined;
+    },
+  });
+
+  // ── views ────────────────────────────────────────────────────────────────
+  // Each view owns its own tree provider and its own commands; the project view
+  // reads the manifest, the cache view runs mcpp's read-only queries, and the
+  // C++ Modules view only forwards to mcppls.
+  const applyViewVisibility = (): void => {
+    // Literal keys, so the wiring gate can see them.
+    // `mcpp.views.enabled` is the master switch: with it off every view is hidden.
+    // Whether VS Code also drops the container's icon from the activity bar is
+    // up to VS Code itself — an extension cannot mark its own container
+    // hidden-when-empty (the setting's description says the same). The `when`
+    // clauses in package.json are negated (`!mcpp.sidebarHidden`) so the default
+    // state is visible — otherwise activation would never run to set the key back.
+    void vscode.commands.executeCommand("setContext", "mcpp.sidebarHidden", !read("mcpp.views.enabled"));
+    void vscode.commands.executeCommand("setContext", "mcpp.views.project", read("mcpp.views.project.show"));
+    void vscode.commands.executeCommand("setContext", "mcpp.views.library", read("mcpp.views.library.show"));
+    void vscode.commands.executeCommand("setContext", "mcpp.views.cache", read("mcpp.views.cache.show"));
+  };
+  applyViewVisibility();
+  extensionContext.subscriptions.push(onConfigurationChanged(applyViewVisibility));
+
+  // The language service is a block inside the project view, so its state source has
+  // to exist before the view is registered.
+  const languageService = registerLanguageServerCommands(extensionContext, { bridge, output });
+  registerProjectView(extensionContext, { currentProject: findCurrentProject, languageService });
+  // The library ecosystem: a sidebar view plus an editor-area package page. The
+  // detail page writes `mcpp.toml` through `mcpp add`, so it tells the view to
+  // refresh — no save event fires for a file written outside the editor.
+  const openLibraryDetail = createLibraryDetailOpener(extensionContext, {
+    mcppExecutable: () => cliController.mcppExecutable(findCurrentProject()),
+    projectRoot: () => findCurrentProject()?.root,
+    output,
+    isTrusted: () => vscode.workspace.isTrusted,
+    onDependenciesChanged: () => void library.refresh(),
+  });
+  const library = registerLibraryView(extensionContext, {
+    projectRoot: () => findCurrentProject()?.root,
+    mcppExecutable: () => cliController.mcppExecutable(findCurrentProject()),
+    openDetail: openLibraryDetail,
+    output,
+    // The cross-registry search runs `mcpp search`, and `mcpp.path` is
+    // resource-scoped: an untrusted workspace must not name the program.
+    isTrusted: () => vscode.workspace.isTrusted,
+  });
+  // `registerLibraryView` registers its own webview provider; these are only the
+  // entry points a menu or the project view can name.
+  extensionContext.subscriptions.push(
+    vscode.commands.registerCommand(LIBRARY_COMMANDS.search, async () => {
+      await vscode.commands.executeCommand("mcpp.library.focus");
+    }),
+    vscode.commands.registerCommand(LIBRARY_COMMANDS.openDetail, async (id: unknown) => {
+      if (typeof id === "string" && id.length > 0) {
+        await openLibraryDetail(id);
+      }
+    }),
+    vscode.commands.registerCommand(LIBRARY_COMMANDS.updateIndex, async () => {
+      if (!vscode.workspace.isTrusted) {
+        void vscode.window.showWarningMessage(
+          t("This workspace is not trusted. mcpp commands may run external programs named by workspace settings; trust the workspace first."),
+        );
+        return;
+      }
+      const project = findCurrentProject();
+      // A refresh that reaches the network is worth a progress notification, and
+      // a refresh that succeeds has to *say so*: the command produced no visible
+      // change at all before, which reads exactly like a broken button.
+      const result = await vscode.window.withProgress(
+        { location: vscode.ProgressLocation.Notification, title: t("Refreshing the mcpp Package Index…") },
+          () =>
+            runMcpp(vscode.workspace.isTrusted, cliController.mcppExecutable(project), ["index", "update"], project?.root, {
+              timeoutMs: 300_000,
+            }),
+        );
+        await library.refresh();
+        if (result === undefined || result.exitCode !== 0) {
+          void vscode.window.showErrorMessage(
+            result === undefined
+              ? t("This workspace is not trusted. mcpp commands may run external programs named by workspace settings; trust the workspace first.")
+              : t("mcpp index update failed with exit code {0}", result.exitCode),
+          );
+          return;
+      }
+      // `library.refresh()` has just filled the snapshot cache, so this second
+      // look is the count the view is showing, not another read of the index.
+      const snapshot = await loadSnapshot(project === undefined ? {} : { projectRoot: project.root });
+      void vscode.window.showInformationMessage(
+        t(
+          "mcpp Package Index refreshed: {0} package(s) from {1} index folder(s).",
+          snapshot.entries.length,
+          snapshot.roots.length,
+        ),
+      );
+    }),
+  );
+  // There is no `mcpp.library.indexFound` context key and no `viewsWelcome`
+  // entry for the library view. `paneview.ts`'s base `ViewPane` answers
+  // `shouldShowWelcome() === false`; only the tree-shaped panes override it, so
+  // welcome content can never render inside a `"type": "webview"` view. The
+  // library view states its own empty case in the document instead, which is the
+  // only place VS Code will show it.
+
+  registerCacheView(extensionContext, {
+    output,
+    currentProject: findCurrentProject,
+    mcppExecutable: (project) => cliController.mcppExecutable(project),
+    isTrusted: () => vscode.workspace.isTrusted,
+  });
+  registerSettingsPanel(extensionContext);
+
+  // Text analysis only: no mcpp process, so both stay available in a restricted
+  // workspace, which is exactly what the `limited` capability promises.
+  registerTomlProviders(
+    extensionContext,
+    () => read("mcpp.toml.completion"),
+    () => ({
+      syntax: read("mcpp.toml.diagnostics.syntax"),
+      unknownSection: read("mcpp.toml.diagnostics.unknownSection"),
+      unknownKey: read("mcpp.toml.diagnostics.unknownKey"),
+      planeSeparation: read("mcpp.toml.diagnostics.planeSeparation"),
+      legacyKeys: read("mcpp.toml.diagnostics.legacyKeys"),
+    }),
+    () => read("mcpp.toml.diagnostics.enabled"),
+    () => read("mcpp.toml.hover"),
+    () => read("mcpp.toml.navigation"),
+  );
+  registerBuildScriptProviders(extensionContext, () => {
+    if (!read("mcpp.buildScript.intelligence") || !read("mcpp.buildScript.diagnostics")) {
+      return "off";
+    }
+    return read<"warning" | "info" | "off">("mcpp.buildScript.diagnostics.severity");
   });
 
   extensionContext.subscriptions.push(
@@ -254,40 +430,35 @@ export async function activate(extensionContext: vscode.ExtensionContext): Promi
     manifestWatcher,
     inProjectContext,
     ...cliController.register(),
-    vscode.languages.registerCompletionItemProvider(
-      { language: "mcpp-toml" },
-      mcppTomlCompletionProvider,
-      "[",
-    ),
-    vscode.commands.registerCommand(CLI_COMMANDS.configureLanguageServer, invokeLanguageServer(
-      () => bridge.selectContext(),
-    )),
-    vscode.commands.registerCommand(DEPRECATED_COMMANDS.configureClangd, invokeLanguageServer(
-      () => bridge.selectContext(),
-    )),
-    vscode.commands.registerCommand(CLI_COMMANDS.refreshCompilationDatabase, runGuarded(async () => {
-      await cliController.runProjectTask("build");
-    })),
-    vscode.commands.registerCommand(CLI_COMMANDS.checkModuleSupport, invokeLanguageServer(
-      () => bridge.restartLanguageServer(),
-    )),
-    vscode.commands.registerCommand(CLI_COMMANDS.showModuleGraph, invokeLanguageServer(
-      () => bridge.showModuleGraph(),
-    )),
-    vscode.commands.registerCommand(CLI_COMMANDS.showLanguageServerLogs, invokeLanguageServer(
-      () => bridge.showLanguageServerLogs(),
-    )),
+
+    // The ids from 0.4.x keep working.
     vscode.commands.registerCommand(CLI_COMMANDS.autoConfigureModules, runGuarded(async () => {
       const project = findCurrentProject();
       if (project === undefined) {
-        await vscode.window.showWarningMessage("当前工作区没有找到 mcpp.toml。");
+        await vscode.window.showWarningMessage(t("This workspace has no mcpp.toml."));
         return;
       }
       await autoConfigureModulesWizard(bridge, cliController, output);
     })),
+    vscode.commands.registerCommand(LEGACY_LANGUAGE_SERVER_COMMANDS.refreshCompilationDatabase, runGuarded(async () => {
+      await cliController.runProjectTask("build");
+    })),
+
+    // Environment self-check: one copyable snapshot of everything a bug report needs.
+    vscode.commands.registerCommand(TOOL_COMMANDS.selfCheck, runGuarded(async () => {
+      await showSelfCheck(output, cliController, bridge, extensionContext.extension.packageJSON.version);
+    })),
+
     vscode.workspace.onDidGrantWorkspaceTrust(() => cliController.refreshStatus()),
   );
 
+  void offerSettingRenames(extensionContext);
+  void noteUnverifiedLanguageService(output);
+
+  if (read("mcpp.diagnostics.selfCheckOnStartup")) {
+    void showSelfCheck(output, cliController, bridge, extensionContext.extension.packageJSON.version);
+  }
+
   extensionContext.subscriptions.push(
     manifestWatcher.onDidCreate(() => cliController.refreshStatus()),
     manifestWatcher.onDidChange(() => cliController.refreshStatus()),
@@ -295,6 +466,114 @@ export async function activate(extensionContext: vscode.ExtensionContext): Promi
   );
 }
 
+/**
+ * The 0.4.x keys that were renamed still hold values nothing reads. Offer to move
+ * them, once per workspace — and leave the old key in place either way, because
+ * deleting a user's setting is their decision.
+ */
+async function offerSettingRenames(context: vscode.ExtensionContext): Promise {
+  const pending = pendingRenames(vscode.window.activeTextEditor?.document.uri);
+  if (pending.length === 0 || context.workspaceState.get("mcpp.renamesOffered") === true) {
+    return;
+  }
+
+  const toUser = t("Move them to my user settings");
+  const toWorkspace = t("Move them to this workspace");
+  const choice = await vscode.window.showInformationMessage(renamePrompt(pending), toUser, toWorkspace);
+  if (choice !== toUser && choice !== toWorkspace) {
+    // Dismissed is not answered: the marker is only written after a choice, so
+    // the offer comes back next session instead of being lost forever — a
+    // marker written before the prompt stranded exactly those users (external
+    // review P2-9).
+    return;
+  }
+  await context.workspaceState.update("mcpp.renamesOffered", true);
+  const moved = await applyRenames(pending, choice === toUser ? "user" : "workspace");
+  void vscode.window.showInformationMessage(t("mcpp: moved {0} setting(s).", moved));
+}
+
+/**
+ * A version notice, never a gate. `extensionDependencies` cannot express a version
+ * range, so a user can legitimately end up with a build of the language service
+ * older than the one this extension was tested against; the capability probe means
+ * that still works, but it is worth one sentence in the log.
+ */
+async function noteUnverifiedLanguageService(output: vscode.OutputChannel): Promise {
+  const version = languageServerVersion();
+  if (version === undefined) {
+    return;
+  }
+  // The same comparator the version matrix uses, against the contract's own
+  // minimum — the old hand-rolled comparison had dead `< 0` branches and a
+  // second, drifting copy of the floor (external review P1-3).
+  const below = compareVersions(version, VERIFIED_MCPPLS_MINIMUM) < 0;
+  if (below) {
+    output.appendLine(
+      t("{0} {1} is older than the verified range ({2}); the capability probe will hide what it cannot do.", MCPPLS_EXTENSION_ID, version, VERIFIED_MCPPLS_RANGE),
+    );
+  }
+}
+
+/**
+ * The self-check gathers, never guesses: anything it cannot read is reported as
+ * unknown rather than left blank. It is the first thing to ask for in a bug
+ * report, and it writes to the `mcpp` channel so it can be copied in one go.
+ */
+async function showSelfCheck(
+  output: vscode.OutputChannel,
+  cliController: McppCliController,
+  bridge: LanguageServerBridge,
+  extensionVersion: unknown,
+): Promise {
+  const project = findCurrentProject();
+  const executable = cliController.mcppExecutable(project);
+  const timeoutSeconds = read("mcpp.runtime.timeoutSeconds");
+  // The untrusted-workspace promise in the manifest is "no mcpp command runs",
+  // and `mcpp.path` is resource-scoped, so the probe refuses rather than
+  // executing a workspace-named program; the report says so in plain words.
+  const probeResult = await runMcpp(vscode.workspace.isTrusted, executable, ["--protocol-version"], project?.root, {
+    timeoutMs: timeoutSeconds > 0 ? timeoutSeconds * 1000 : undefined,
+  });
+  const info = probeResult !== undefined && probeResult.exitCode === 0 ? parseProtocolInfo(probeResult.stdout) : undefined;
+  const state = readLanguageServerState();
+  const capabilities = CAPABILITIES.map((entry) => ({
+    key: entry.key,
+    state: bridge.isGone(entry.key) ? "missing" : bridge.isUnconfirmed(entry.key) ? "unconfirmed" : "available",
+  }));
+  const text = buildSelfCheckText({
+    extensionVersion: typeof extensionVersion === "string" ? extensionVersion : "unknown",
+    vscodeVersion: vscode.version,
+    platform: `${process.platform}-${process.arch}`,
+    languagePreference: languagePreference(),
+    trusted: vscode.workspace.isTrusted,
+    workspaceRoots: (vscode.workspace.workspaceFolders ?? []).map((folder) => folder.uri.fsPath),
+    projectRoot: project?.root,
+    mcppPath: executable,
+    mcppProbe:
+      info === undefined
+        ? undefined
+        : { version: info.mcppVersion, envelopeMax: info.envelopeMax, kinds: Object.keys(info.kinds) },
+    mcppls: {
+      installed: languageServerInstalled(),
+      version: languageServerVersion(),
+      enabled: languageServerEnabled(),
+      state: describeState(state),
+      capabilities,
+    },
+    changedSettings: changedSettings(project === undefined ? undefined : vscode.Uri.file(project.root)),
+    lastRefresh: lastRefresh,
+    cache: await readCacheSnapshot(),
+  });
+  output.appendLine("");
+  output.appendLine("===== mcpp: environment self-check =====");
+  output.appendLine(text);
+  if (probeResult === undefined) {
+    output.appendLine(t("The workspace is not trusted; mcpp itself was not probed."));
+  }
+  output.appendLine("========================================");
+  output.show(true);
+}
+
 export function deactivate(): void {
   // VS Code disposes everything registered in activate().
 }
diff --git a/src/i18n/t.ts b/src/i18n/t.ts
new file mode 100644
index 0000000..f36c3af
--- /dev/null
+++ b/src/i18n/t.ts
@@ -0,0 +1,81 @@
+/**
+ * Runtime strings, in one place, following the editor's language by default.
+ *
+ * The **English text is the key** (the same convention `vscode.l10n` uses), so a
+ * missing translation degrades to readable English rather than to an identifier.
+ * `data/i18n/zh-cn.json` carries the translations; `tools/generate-l10n.mjs`
+ * turns it into `l10n/bundle.l10n.zh-cn.json`, which is what makes `auto` work
+ * inside VS Code.
+ *
+ * `mcpp.ui.language` overrides the choice for **our** strings — runtime messages
+ * and our webviews. It cannot change the command palette or the Settings UI:
+ * VS Code resolves `package.nls.*` once at startup from its own locale. That
+ * limitation is documented in `docs/settings.md` and stated in the panel.
+ */
+
+import type * as vscode from "vscode";
+
+import zhCn from "../../data/i18n/zh-cn.json";
+import { format, translate, type Bundle, type LanguagePreference } from "./translate";
+
+export type { LanguagePreference } from "./translate";
+
+const BUNDLES: Readonly> = {
+  en: {},
+  "zh-cn": zhCn as Bundle,
+};
+
+let preference: LanguagePreference = "auto";
+
+/** The effective preference, for the environment self-check and the panel. */
+export function languagePreference(): LanguagePreference {
+  return preference;
+}
+
+export function setLanguagePreference(value: LanguagePreference | undefined): void {
+  preference = value === "en" || value === "zh-cn" ? value : "auto";
+}
+
+export type Substitution = string | number | boolean;
+
+/**
+ * The editor's own `l10n`, loaded on demand.
+ *
+ * `t()` needs it only on the `auto` path, so requiring it lazily keeps this
+ * module importable from **pure** modules: the TOML completion tables are unit
+ * tested without an editor, and importing them must not fail on a missing
+ * `vscode`. Outside an editor host there is no locale to consult, and the
+ * English text — which is the key — is the correct answer: it is exactly what a
+ * missing translation degrades to.
+ */
+function editorL10n(): typeof vscode.l10n | undefined {
+  try {
+    return (require("vscode") as typeof vscode).l10n;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve one runtime string.
+ *
+ * - `auto` asks VS Code, which consults `l10n/bundle.l10n..json` and
+ *   falls back to the English text we passed in;
+ * - a manual preference reads our own bundle, so the escape hatch works even
+ *   when the editor is in a third language.
+ */
+export function t(english: string, ...args: readonly Substitution[]): string {
+  if (preference === "auto") {
+    const l10n = editorL10n();
+    return l10n === undefined ? format(english, args) : l10n.t(english, ...args);
+  }
+  return translate(preference, english, args, BUNDLES[preference]);
+}
+
+/** Substitute into an already-translated template (webviews, generated HTML). */
+export { format };
+
+/** The bundle this build ships, for `tools/l10n-check.mjs`. */
+export function translationBundle(): Bundle {
+  return BUNDLES["zh-cn"];
+}
diff --git a/src/i18n/translate.ts b/src/i18n/translate.ts
new file mode 100644
index 0000000..122b706
--- /dev/null
+++ b/src/i18n/translate.ts
@@ -0,0 +1,55 @@
+/**
+ * The language-independent half of `src/i18n/t.ts`. Pure: no `vscode`, so the
+ * resolution rules are unit-testable.
+ *
+ * English text is the key; a translation bundle maps it to the target language.
+ * A missing entry returns the English text, which is why a forgotten translation
+ * reads as English rather than as an identifier.
+ */
+
+export type LanguagePreference = "auto" | "en" | "zh-cn";
+export type Bundle = Readonly>;
+
+/** `{0}`-style substitution, the same placeholder syntax `vscode.l10n` uses. */
+export function format(template: string, args: readonly unknown[]): string {
+  return template.replace(/\{(\d+)\}/g, (whole, index: string) => {
+    const value = args[Number.parseInt(index, 10)];
+    return value === undefined ? whole : String(value);
+  });
+}
+
+/**
+ * Resolve one string for an explicit preference. `auto` is not handled here:
+ * that path belongs to VS Code, which owns the editor's locale.
+ */
+export function translate(
+  preference: Exclude,
+  english: string,
+  args: readonly unknown[],
+  bundle: Bundle,
+): string {
+  if (preference === "en") {
+    return format(english, args);
+  }
+  const translated = bundle[english];
+  return format(typeof translated === "string" && translated.length > 0 ? translated : english, args);
+}
+
+/** `"zh-cn"` for any Chinese locale VS Code may report; `undefined` otherwise. */
+export function localeFromEditorLanguage(language: string | undefined): "en" | "zh-cn" | undefined {
+  if (language === undefined) {
+    return undefined;
+  }
+  return language.toLowerCase().startsWith("zh") ? "zh-cn" : "en";
+}
+
+/** Missing entries for a set of used strings, for `tools/l10n-check.mjs`. */
+export function missingTranslations(used: Iterable, bundle: Bundle): string[] {
+  const missing: string[] = [];
+  for (const key of used) {
+    if (typeof bundle[key] !== "string" || bundle[key].length === 0) {
+      missing.push(key);
+    }
+  }
+  return missing;
+}
diff --git a/src/ideWorkflow.ts b/src/ideWorkflow.ts
deleted file mode 100644
index 954ae55..0000000
--- a/src/ideWorkflow.ts
+++ /dev/null
@@ -1,45 +0,0 @@
-import type { ProcessResult } from "./process";
-
-export interface IdeConfigurationRequest {
-  projectRoot: string;
-  compilationDatabasePath: string;
-  trusted: boolean;
-  force?: boolean;
-  databaseValid: () => boolean;
-  configure: () => Promise;
-}
-
-export type IdeConfigurationOutcome =
-  | { state: "configured"; compileCommands: string }
-  | { state: "existing"; compileCommands: string }
-  | { state: "failed"; compileCommands?: string; exitCode: number }
-  | { state: "untrusted"; compileCommands?: string };
-
-/**
- * 决定是否需要执行 mcpp build --configure-only；不在这里读写 VS Code 设置，
- * 便于 Extension Host 和纯 Node 测试共享同一套生命周期边界。
- */
-export async function ensureIdeConfigured(
-  request: IdeConfigurationRequest,
-): Promise {
-  const validBefore = request.databaseValid();
-  if (!request.trusted) {
-    return {
-      state: "untrusted",
-      ...(validBefore ? { compileCommands: request.compilationDatabasePath } : {}),
-    };
-  }
-  if (validBefore && !request.force) {
-    return { state: "existing", compileCommands: request.compilationDatabasePath };
-  }
-  const result = await request.configure();
-  const validAfter = request.databaseValid();
-  if (result.exitCode === 0 && validAfter) {
-    return { state: "configured", compileCommands: request.compilationDatabasePath };
-  }
-  return {
-    state: "failed",
-    ...(validAfter ? { compileCommands: request.compilationDatabasePath } : {}),
-    exitCode: result.exitCode,
-  };
-}
diff --git a/src/languageServer.ts b/src/languageServer.ts
deleted file mode 100644
index 509cde8..0000000
--- a/src/languageServer.ts
+++ /dev/null
@@ -1,80 +0,0 @@
-export const MCPPLS_EXTENSION_ID = "sunrisepeak.mcpp-language-server";
-
-export const MCPPLS_COMMANDS = {
-  restart: "mcppls.restartServer",
-  selectContext: "mcppls.selectContext",
-  graph: "mcppls.showModuleGraph",
-  logs: "mcppls.showLogs",
-} as const;
-
-export type LanguageServerCommandState = "completed" | "unavailable" | "failed";
-
-export interface LanguageServerCommandResult {
-  state: LanguageServerCommandState;
-  message: string;
-}
-
-export interface LanguageServerCommandExecutor {
-  extensionInstalled(id: string): boolean;
-  /** Activate the dependency before forwarding a command when VS Code has not activated it yet. */
-  activateExtension?(id: string): Thenable;
-  executeCommand(command: string, ...args: unknown[]): Thenable;
-}
-
-export interface LanguageServerBridge {
-  restartLanguageServer(): Promise;
-  refreshLanguageServerAfterBuild(): Promise;
-  selectContext(): Promise;
-  showModuleGraph(): Promise;
-  showLanguageServerLogs(): Promise;
-}
-
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-export function createLanguageServerBridge(
-  executor: LanguageServerCommandExecutor,
-): LanguageServerBridge {
-  let refreshInFlight: Promise | undefined;
-
-  async function invoke(command: string, successMessage: string): Promise {
-    if (!executor.extensionInstalled(MCPPLS_EXTENSION_ID)) {
-      return {
-        state: "unavailable",
-        message: `C++ 模块语言服务依赖未安装或已禁用：${MCPPLS_EXTENSION_ID}。`,
-      };
-    }
-    try {
-      await executor.activateExtension?.(MCPPLS_EXTENSION_ID);
-      await executor.executeCommand(command);
-      return { state: "completed", message: successMessage };
-    } catch (error) {
-      return {
-        state: "failed",
-        message: `C++ Modules 命令执行失败：${errorMessage(error)}`,
-      };
-    }
-  }
-
-  async function restartLanguageServer(): Promise {
-    return invoke(MCPPLS_COMMANDS.restart, "C++ 模块语言服务已重启。");
-  }
-
-  function refreshLanguageServerAfterBuild(): Promise {
-    if (refreshInFlight !== undefined) {
-      return refreshInFlight;
-    }
-    refreshInFlight = invoke(MCPPLS_COMMANDS.restart, "C++ 模块语言服务已刷新。")
-      .finally(() => { refreshInFlight = undefined; });
-    return refreshInFlight;
-  }
-
-  return {
-    restartLanguageServer,
-    refreshLanguageServerAfterBuild,
-    selectContext: () => invoke(MCPPLS_COMMANDS.selectContext, "已打开 C++ 模块上下文选择。"),
-    showModuleGraph: () => invoke(MCPPLS_COMMANDS.graph, "已打开 C++ 模块图。"),
-    showLanguageServerLogs: () => invoke(MCPPLS_COMMANDS.logs, "已打开 C++ Modules 日志。"),
-  };
-}
diff --git a/src/library/addDependency.ts b/src/library/addDependency.ts
new file mode 100644
index 0000000..d761851
--- /dev/null
+++ b/src/library/addDependency.ts
@@ -0,0 +1,142 @@
+/**
+ * `mcpp add @ [--dev]` — the only way this extension changes a
+ * project's dependencies.
+ *
+ * **`mcpp.toml` is never written here.** `mcpp add` is the official "add a
+ * dependency to mcpp.toml" command; it owns the file's formatting, comments and
+ * lockfile. Editing TOML from an extension is how a manifest gets corrupted.
+ *
+ * The version is **mandatory**, and that is mcpp's rule, not ours: a bare
+ * `mcpp add compat.argparse` is refused with
+ * `error: package version required: \`mcpp add compat.argparse@\` (M2 supports
+ * exact-version only)`. The caller therefore always passes the version it picked
+ * from `mcpp xpkg parse --json` (the greatest one for this platform), and this
+ * module refuses to run without one rather than producing an error the user
+ * cannot act on.
+ *
+ * Failures are values, not exceptions: the exit code and the stderr tail travel
+ * back to the caller, which shows them. Nothing here throws, so a failed add can
+ * never leave the detail page half-rendered.
+ */
+
+import * as vscode from "vscode";
+
+import { runMcpp } from "../cli/process";
+import { read } from "../config/access";
+import { t } from "../i18n/t";
+import { clampOutput } from "../util/text";
+
+/** `mcpp add` may have to fetch an index or build the cache entry, so it gets a long budget. */
+const ADD_TIMEOUT_MS = 300_000;
+
+export interface AddDependencyDeps {
+  /** The configured `mcpp` path, or `mcpp`. */
+  mcppExecutable: () => string;
+  /** The workspace folder holding `mcpp.toml`; `undefined` is a refusal, not a crash. */
+  projectRoot: () => string | undefined;
+  /** Where the command and its output are logged, the same channel the CLI uses. */
+  output?: vscode.OutputChannel;
+  /** `vscode.workspace.isTrusted`; an untrusted workspace may not be written to. */
+  isTrusted: () => boolean;
+}
+
+export interface AddDependencyRequest {
+  /** The package id, `ns.name`. */
+  id: string;
+  /** The exact version; `undefined` is refused. */
+  version?: string;
+  /** `--dev`, i.e. a `[dev-dependencies]` entry. */
+  dev: boolean;
+}
+
+export interface AddDependencyResult {
+  ok: boolean;
+  /** The argv that ran (empty when nothing ran), for the log and the UI. */
+  argv: string[];
+  exitCode: number;
+  /** A sentence for the detail page, already localized. */
+  message: string;
+}
+
+function failure(message: string, argv: readonly string[] = []): AddDependencyResult {
+  return { ok: false, argv: [...argv], exitCode: 1, message };
+}
+
+/** The argv of one add, without running it. The preview in the UI uses the same shape. */
+export function addDependencyArgv(request: { id: string; version: string; dev: boolean }): string[] {
+  return ["add", `${request.id}@${request.version}`, ...(request.dev ? ["--dev"] : [])];
+}
+
+/**
+ * Run one `mcpp add`, with a progress notification, and report what happened.
+ *
+ * Every refusal is explicit and happens **before** anything runs: no version, no
+ * `mcpp.toml`, an untrusted workspace. A run that fails returns the exit code and
+ * the last lines of stderr, which the detail page prints verbatim — the user gets
+ * mcpp's own words, not ours.
+ */
+export async function addDependency(
+  deps: AddDependencyDeps,
+  request: AddDependencyRequest,
+): Promise {
+  const version = request.version?.trim() ?? "";
+  if (request.id.trim().length === 0 || version.length === 0) {
+    const message = t("mcpp add needs an exact version: mcpp add {0}@.", request.id);
+    void vscode.window.showWarningMessage(message);
+    return failure(message);
+  }
+  const root = deps.projectRoot();
+  if (root === undefined) {
+    const message = t("This workspace has no mcpp.toml.");
+    void vscode.window.showWarningMessage(message);
+    return failure(message);
+  }
+  if (!deps.isTrusted()) {
+    const message = t("This workspace is not trusted. mcpp commands that write are disabled until you trust it.");
+    void vscode.window.showWarningMessage(message);
+    return failure(message);
+  }
+
+  const argv = addDependencyArgv({ id: request.id, version, dev: request.dev });
+  const executable = deps.mcppExecutable();
+  const result = await vscode.window.withProgress(
+    { location: vscode.ProgressLocation.Notification, title: t("Adding {0}…", request.id) },
+    () =>
+      runMcpp(deps.isTrusted(), executable, argv, root, {
+        timeoutMs: ADD_TIMEOUT_MS,
+        maxBufferMiB: read("mcpp.runtime.maxOutputMiB"),
+      }),
+  );
+  if (result === undefined) {
+    // The seam refused: the guard above usually answers first with a friendlier
+    // message, so this is the defensive spelling of the same refusal.
+    const message = t("This workspace is not trusted. mcpp commands that write are disabled until you trust it.");
+    return failure(message);
+  }
+
+  try {
+    deps.output?.appendLine(`\n[${new Date().toISOString()}] mcpp ${argv.join(" ")}`);
+    deps.output?.appendLine(`$ ${[executable, ...argv].join(" ")}`);
+    const stdout = clampOutput(result.stdout);
+    const stderr = clampOutput(result.stderr);
+    if (stdout.text.trim().length > 0) deps.output?.appendLine(stdout.text.trimEnd());
+    if (stderr.text.trim().length > 0) deps.output?.appendLine(stderr.text.trimEnd());
+    deps.output?.appendLine(`[exit ${result.exitCode}]`);
+  } catch {
+    // The channel can already be gone during shutdown.
+  }
+
+  if (result.exitCode === 0) {
+    const message = t("Added {0} to mcpp.toml.", `${request.id}@${version}`);
+    void vscode.window.showInformationMessage(message);
+    return { ok: true, argv, exitCode: 0, message };
+  }
+
+  const detail = clampOutput(result.stderr.length > 0 ? result.stderr : result.stdout).text.trim();
+  const message =
+    detail.length === 0
+      ? t("mcpp add failed with exit code {0}.", result.exitCode)
+      : t("mcpp add failed with exit code {0}: {1}", result.exitCode, detail);
+  void vscode.window.showErrorMessage(message);
+  return { ok: false, argv, exitCode: result.exitCode, message };
+}
diff --git a/src/library/detailHtml.ts b/src/library/detailHtml.ts
new file mode 100644
index 0000000..1c6d292
--- /dev/null
+++ b/src/library/detailHtml.ts
@@ -0,0 +1,713 @@
+/**
+ * The package detail page's document, as a pure function (plan §12.1–§12.5).
+ *
+ * The sidebar answers "which package"; this page answers "what is it, how do I
+ * consume it, and how do I add it". It opens in the **editor area** (a
+ * `WebviewPanel`, see `src/library/detailPanel.ts`), because a 200 px sidebar
+ * cannot show a version matrix and a code block.
+ *
+ * The same house rules as the other webviews apply: strict CSP, every label from
+ * `DetailModel.ui`, every interpolation escaped, no inline `style=`, and no state
+ * that is only a colour. Everything shown is either authoritative
+ * (`mcpp xpkg parse --json`, `mcpp.toml`) or explicitly attributed (the example
+ * code comes from the index's own CI-built test projects, and says so).
+ *
+ * The example block is tokenized by `indexModel.tokenizeCppLine` — a deliberately
+ * small highlighter: comments, strings, the preprocessor directive, a short
+ * keyword list and punctuation. It is not a parser and is not meant to be.
+ */
+
+import {
+  BADGE_UI,
+  surfaceLabel,
+  tokenizeCppLine,
+  type BadgeKey,
+  type Surface,
+} from "./indexModel";
+
+/** One platform's row in the version matrix. */
+export interface DetailVersionGroup {
+  platform: string;
+  versions: string[];
+  /** The platform this extension host is running on. */
+  current: boolean;
+}
+
+/** One declared dependency, as far as it is cheaply known. */
+export interface DetailDependency {
+  id: string;
+  version?: string;
+  /** The version the project's `mcpp.lock` resolved, when it is known. */
+  resolved?: string;
+}
+
+/** One window of real example code. */
+export interface DetailSnippet {
+  file: string;
+  startLine: number;
+  lines: string[];
+  usageLine: number;
+}
+
+/** The outcome of the last `mcpp add`, shown in place. */
+export interface DetailResult {
+  /** `pending` is the client's own "I asked the host" line, replaced by the answer. */
+  state: "ok" | "error" | "pending";
+  message: string;
+}
+
+/** The workspace's own answer about one package. */
+export interface DetailInstalled {
+  version: string;
+  /** Declared under `[dev-dependencies]`. */
+  dev: boolean;
+}
+
+export interface DetailModel {
+  /** Everything is already localized by the caller. */
+  ui: Record;
+  id: string;
+  name: string;
+  description?: string;
+  licenses: string[];
+  repo?: string;
+  registry: string;
+  surface?: Surface;
+  surfaces: Surface[];
+  badges: BadgeKey[];
+  /** The version matrix, current platform first. */
+  versions: DetailVersionGroup[];
+  /** Every version the current platform has, greatest first. */
+  currentVersions: string[];
+  /** What `mcpp add` would use by default. */
+  latest?: string;
+  /**
+   * The version this workspace already asks for — `mcpp.toml` first, then
+   * `mcpp.lock` — so the page can say "you have this one" and offer the switch
+   * instead of a blind add. Absent when the project does not depend on the
+   * package, or when the dependency names no version (a path or git entry).
+   */
+  installed?: DetailInstalled;
+  standard?: string;
+  dependencies: DetailDependency[];
+  includeDirs: string[];
+  targets: string[];
+  snippets: DetailSnippet[];
+  /** The example project the snippets come from, when there is one. */
+  exampleProject?: string;
+  /**
+   * How a reader brings the package into code (§22): the example project's
+   * real `import …;` / `#include …` lines when there are any, else the honest
+   * synthetic form for the surface. Empty when the surface is not importable.
+   */
+  usage: string[];
+  /** The index site's package page; omitted for a registry that has no site. */
+  indexUrl?: string;
+  /** `mcpp add {0}@{1}` / with `--dev`, so the preview and the run agree. */
+  commandTemplate: string;
+  commandDevTemplate: string;
+  /** Set when `mcpp xpkg parse` could not be read; the page still renders. */
+  parseNotice?: string;
+  /** The data source, in plain words, for the footer. */
+  dataSource: string;
+  result?: DetailResult;
+}
+
+export interface DetailAssets {
+  cspSource: string;
+  nonce: string;
+  styleUri: string;
+}
+
+/** The `ui` keys the renderer reads, so the caller and the renderer cannot drift. */
+export const DETAIL_UI = {
+  htmlLang: "detail.htmlLang",
+  title: "detail.title",
+  overview: "detail.overview",
+  license: "detail.license",
+  repo: "detail.repo",
+  openRepo: "detail.openRepo",
+  registry: "detail.registry",
+  surface: "detail.surface",
+  surfaceExternal: "detail.surface.external",
+  standard: "detail.standard",
+  versions: "detail.versions",
+  versionsAll: "detail.versions.all",
+  versionsCurrent: "detail.versions.current",
+  versionsNone: "detail.versions.none",
+  versionsPick: "detail.versions.pick",
+  dependencies: "detail.dependencies",
+  dependenciesNone: "detail.dependencies.none",
+  dependenciesHint: "detail.dependencies.hint",
+  resolved: "detail.resolved",
+  code: "detail.code",
+  codeNone: "detail.code.none",
+  codeSource: "detail.code.source",
+  codeProject: "detail.code.project",
+  add: "detail.add",
+  addDev: "detail.addDev",
+  switchTo: "detail.switchTo",
+  alreadyAdded: "detail.alreadyAdded",
+  installed: "detail.installed",
+  opening: "detail.opening",
+  addLatest: "detail.addLatest",
+  addNoVersion: "detail.add.noVersion",
+  command: "detail.command",
+  usage: "detail.usage",
+  copy: "detail.copy",
+  copied: "detail.copied",
+  copying: "detail.copying",
+  indexLink: "detail.indexLink",
+  badgeExamples: BADGE_UI.examples.key,
+  badgeCn: BADGE_UI.cn.key,
+  badgeOpenkalEcosystem: BADGE_UI["openkal-ecosystem"].key,
+  badgeOpenkalCompat: BADGE_UI["openkal-compat"].key,
+  badgeOpenkalPosix: BADGE_UI["openkal-posix"].key,
+  badgeOpenkalPlatform: BADGE_UI["openkal-platform"].key,
+  targets: "detail.targets",
+  includeDirs: "detail.includeDirs",
+} as const;
+
+const BADGE_KEY_UI: Readonly> = {
+  examples: DETAIL_UI.badgeExamples,
+  cn: DETAIL_UI.badgeCn,
+  "openkal-ecosystem": DETAIL_UI.badgeOpenkalEcosystem,
+  "openkal-compat": DETAIL_UI.badgeOpenkalCompat,
+  "openkal-posix": DETAIL_UI.badgeOpenkalPosix,
+  "openkal-platform": DETAIL_UI.badgeOpenkalPlatform,
+};
+
+/**
+ * What the page says to the host.
+ *
+ * There is no `ready`: the document is already the whole model, and a page that
+ * announces its own load only invites the host to render it again — which is
+ * exactly the reload loop the *library sidebar* shipped with (see the note in
+ * `libraryHtml.ts`). This host happened to answer `ready` with an empty `return`,
+ * so the trap never fired here; it is gone all the same.
+ */
+export type DetailMessage =
+  | { type: "add"; version: string; dev: boolean }
+  | { type: "openUrl"; url: string }
+  | { type: "copy"; text: string };
+
+export type UiLabel = (key: string) => string;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&")
+    .replace(//g, ">")
+    .replace(/"/g, """)
+    .replace(/'/g, "'");
+}
+
+function escapeCsp(value: string): string {
+  return value.replace(/&/g, "&").replace(//g, ">").replace(/"/g, """);
+}
+
+function attribute(name: string, value: string | number | undefined): string {
+  return value === undefined ? "" : ` ${name}="${escapeHtml(String(value))}"`;
+}
+
+function flag(name: string, on: boolean): string {
+  return on ? ` ${name}` : "";
+}
+
+/** `{0}`-style substitution into an already-localized ui string. */
+function fill(label: UiLabel, key: string, args: readonly (string | number)[]): string {
+  return label(key).replace(/\{(\d+)\}/g, (whole, index: string) => {
+    const value = args[Number(index)];
+    return value === undefined ? whole : String(value);
+  });
+}
+
+function badgeLabels(badges: readonly BadgeKey[], label: UiLabel): string[] {
+  return badges.map((badge) => label(BADGE_KEY_UI[badge]));
+}
+
+/** One source line, tokenized. The renderer escapes every token. */
+function renderLine(line: string, usage: boolean): string {
+  if (line.length === 0) {
+    return "\n";
+  }
+  const tokens = tokenizeCppLine(line)
+    .map((token) => `${escapeHtml(token.text)}`)
+    .join("");
+  return `${tokens}\n`;
+}
+
+function renderSnippets(model: DetailModel, label: UiLabel): string {
+  if (model.snippets.length === 0) {
+    return `${escapeHtml(label(DETAIL_UI.codeNone))}`;
+  }
+  const blocks = model.snippets.map((snippet) => {
+    const lines = snippet.lines
+      .map((line, index) => renderLine(line, snippet.startLine + index === snippet.usageLine))
+      .join("");
+    const caption = fill(label, DETAIL_UI.codeSource, [snippet.file, snippet.startLine]);
+    return [
+      `${lines}`,
+      `${escapeHtml(caption)}`,
+    ].join("\n");
+  });
+  return blocks.join("\n");
+}
+
+/**
+ * The version matrix, as the page's **selector**: each version is a button that
+ * aims the command at the top of the page at itself.
+ *
+ * A `${escapeHtml(label(DETAIL_UI.addDev))}`,
+    ...(model.repo === undefined ? [] : [link(model.repo, label(DETAIL_UI.openRepo))]),
+    ...(model.indexUrl === undefined ? [] : [link(model.indexUrl, label(DETAIL_UI.indexLink))]),
+    `  `,
+    // The copy button sits beside the command, not inside it: `command.textContent`
+    // is what a click copies, and a button inside the paragraph would be copied too.
+    `  `,
+    `    ${escapeHtml(command)}`,
+    `    `,
+    `  `,
+    disabled
+      ? `  ${escapeHtml(label(DETAIL_UI.addNoVersion))}`
+      : `  ${escapeHtml(label(DETAIL_UI.addLatest))}`,
+    ...usage,
+    `  ${escapeHtml(model.result?.message ?? "")}`,
+    `

${renderActions(model, label)} -

${escapeHtml(versionsHeading)}

- ${renderVersions(model, label)} -

${escapeHtml(label(DETAIL_UI.dependencies))}

- ${renderDependencies(model, label)} -

${escapeHtml(label(DETAIL_UI.code))}

- ${renderSnippets(model, label)} - ${model.exampleProject === undefined ? "" : `

${escapeHtml(fill(label, DETAIL_UI.codeProject, [model.exampleProject]))}

`} -

${escapeHtml(label(DETAIL_UI.overview))}

- ${renderExtras(model, label)} - ${model.parseNotice === undefined ? "" : `

${escapeHtml(model.parseNotice)}

`} -

+ + ${model.preview ? "" : `

${escapeHtml(label(DETAIL_UI.usage))}

+ ${model.usage.length ? `

${escapeHtml(label(DETAIL_UI.usageSource))}

` + model.usage.map((line) => `

${escapeHtml(line)}

`).join("") : model.snippets.length ? "" : `

${escapeHtml(label(DETAIL_UI.unknownUsage))}

`} + ${model.snippets.length ? renderSnippets(model, label) : ""} + ${model.exampleProject === undefined ? "" : `

${escapeHtml(fill(label, DETAIL_UI.codeProject, [model.exampleProject]))}

`} + ${model.exampleProvenance === undefined ? "" : `

${escapeHtml(model.exampleProvenance)}

`} +

+ +

- + @@ -691,6 +655,15 @@ export function decodeDetailMessage(raw: unknown): DetailMessage | undefined { return undefined; } switch (raw.type) { + case "mounted": + case "selectProject": + case "showOutput": + case "retry": + case "openManifest": + return { type: raw.type }; + case "openDependency": + case "openFile": + return nonEmptyString(raw.key) ? { type: raw.type, key: raw.key } : undefined; case "add": return nonEmptyString(raw.version) && typeof raw.dev === "boolean" ? { type: "add", version: raw.version, dev: raw.dev } @@ -705,7 +678,7 @@ export function decodeDetailMessage(raw: unknown): DetailMessage | undefined { // hostile document cannot park a novel in the clipboard — and everything // else about the text is the user's own click. return nonEmptyString(raw.text) && raw.text.length <= 16_384 - ? { type: "copy", text: raw.text } + ? { type: "copy", text: raw.text, ...(typeof raw.token === "string" && /^copy-\d+$/.test(raw.token) ? { token: raw.token } : {}) } : undefined; default: return undefined; diff --git a/src/library/detailPanel.ts b/src/library/detailPanel.ts index b784b26..2fb0adb 100644 --- a/src/library/detailPanel.ts +++ b/src/library/detailPanel.ts @@ -18,7 +18,7 @@ * file. */ -import { readFileSync } from "node:fs"; +import { existsSync, readFileSync } from "node:fs"; import * as path from "node:path"; import * as vscode from "vscode"; @@ -27,28 +27,28 @@ import { read } from "../config/access"; import { languagePreference, t } from "../i18n/t"; import { localeFromEditorLanguage } from "../i18n/translate"; import { WebviewDocument } from "../webview/document"; +import { projectDependencyState, readProjectDeclarations, operationMatches } from "./projectState"; +import type { LibraryRow } from "./libraryHtml"; import { addDependency } from "./addDependency"; import { badgesOf, - codeSnippets, descriptorDependencies, - installedFor, lockPackageVersions, mergeSurfaces, parseXpkgJson, platformKey, surfaceLabel, - syntheticUsageLines, usageLinesFor, type LibraryEntry, type Surface, } from "./indexModel"; import { cachedDescriptorText, loadSnapshot, readDescriptorText, readExampleFiles } from "./indexLocator"; +import { bundledExample, ExampleDocuments, EXAMPLE_SCHEME } from "./examples"; import { DETAIL_UI, decodeDetailMessage, renderDetailHtml, - type DetailInstalled, + detailClientState, type DetailModel, type DetailVersionGroup, type DetailResult, @@ -63,7 +63,9 @@ const STYLESHEET = "library.css"; const PARSE_TIMEOUT_MS = 20_000; export interface DetailPanelDeps { - mcppExecutable: () => string; + mcppExecutable: (projectRoot?: string) => string; + chooseProject?: () => Promise; + onPackageOpened?: (key: string) => void; projectRoot: () => string | undefined; output: vscode.OutputChannel; isTrusted: () => boolean; @@ -74,19 +76,30 @@ export interface DetailPanelDeps { * library view's `refresh()`. */ onDependenciesChanged?: () => void; + onProjectFilesRead?: (root: string, manifest: string, lock: string) => void; } /** Build the opener once; `extension.ts` passes `openLibraryDetail` to the view. */ export function createLibraryDetailOpener( context: vscode.ExtensionContext, deps: DetailPanelDeps, -): (id: string) => Promise { +): LibraryDetailOpener { + const sourceChanged = new vscode.EventEmitter(); + const exampleDocuments = new ExampleDocuments((uri) => sourceChanged.fire(vscode.Uri.parse(uri))); + context.subscriptions.push(sourceChanged, vscode.workspace.registerTextDocumentContentProvider(EXAMPLE_SCHEME, { + onDidChange: sourceChanged.event, + provideTextDocumentContent: (uri) => exampleDocuments.read(uri.toString()) ?? "", + })); const session: DetailSession = { context, + exampleDocuments, deps, panel: undefined, id: undefined, busy: false, + generation: 0, + projectRoot: deps.projectRoot(), + painted: false, webviewDocument: new WebviewDocument(STYLESHEET), }; context.subscriptions.push({ @@ -95,17 +108,41 @@ export function createLibraryDetailOpener( session.panel = undefined; }, }); - return (id: string) => open(session, id); + const opener = (id: string, preview?: LibraryRow) => open(session, id, preview); + opener.refresh = async () => { + if (session.id === undefined || session.panel === undefined) { return; } + const root = deps.projectRoot(); + if (root !== session.projectRoot) { + session.projectRoot = root; session.generation++; session.result = undefined; + if (session.model) { paintModel(session, { ...session.model, generation: session.generation, projectRoot: root, projectState: undefined, installed: undefined, loading: true, blockedReason: t("Reading package details…"), result: undefined }); } + } + await render(session, session.id); + }; + return opener; +} + +export interface LibraryDetailOpener { + (id: string, preview?: LibraryRow): Promise; + refresh(): Promise; } /** One panel per window, remembered so a second `open` reveals rather than stacks. */ export interface DetailSession { + exampleDocuments: ExampleDocuments; context: vscode.ExtensionContext; deps: DetailPanelDeps; panel: vscode.WebviewPanel | undefined; id: string | undefined; /** `mcpp add` in flight: a second click must not start a second command. */ busy: boolean; + generation: number; + renderRequest?: number; + projectRoot?: string; + preview?: LibraryRow; + model?: DetailModel; + painted: boolean; + lastHtml?: string; + result?: DetailResult; /** * The document and its nonce, kept per session so re-opening the *same* * package renders byte for byte the same document and does not reload the @@ -117,7 +154,7 @@ export interface DetailSession { /** The parse result per descriptor, so re-opening a package costs no process. */ const parsed = new Map(); -export async function open(session: DetailSession, id: string): Promise { +export async function open(session: DetailSession, id: string, preview?: LibraryRow): Promise { if (session.panel === undefined) { const panel = vscode.window.createWebviewPanel( PANEL_VIEW_TYPE, @@ -133,6 +170,9 @@ export async function open(session: DetailSession, id: string): Promise { panel.onDidDispose(() => { session.panel = undefined; session.id = undefined; + session.generation++; + session.painted = false; + session.lastHtml = undefined; // The next open creates a brand-new webview: what was on screen says // nothing about it, so the document comparison starts from nothing. session.webviewDocument.invalidate(); @@ -142,161 +182,198 @@ export async function open(session: DetailSession, id: string): Promise { }); } const panel = session.panel; + const changed = session.id !== id; session.id = id; - panel.title = id; + session.preview = preview; + session.deps.onPackageOpened?.(id); + if (changed) { session.generation++; session.result = undefined; } + const nextProject = session.deps.projectRoot(); + if (nextProject !== session.projectRoot) { session.generation++; session.result = undefined; } + session.projectRoot = nextProject; + panel.title = preview?.id ?? path.basename(id, ".lua"); + if (changed || !session.painted) { + const loading = emptyModel(preview?.id ?? path.basename(id, ".lua"), labels(), t("Reading package details…")); + loading.key = id; loading.generation = session.generation; loading.projectRoot = session.projectRoot; + loading.loading = true; loading.blockedReason = t("Reading package details…"); + paintModel(session, loading); + } panel.reveal(vscode.ViewColumn.Active, false); await render(session, id); } async function handle(session: DetailSession, raw: unknown): Promise { const message = decodeDetailMessage(raw); - if (message === undefined || session.panel === undefined) { + if (message === undefined || session.panel === undefined || session.id === undefined) { return; } + const envelope = raw as { pageKey?: unknown; generation?: unknown }; + if (message.type === "mounted") { + if (session.model) { paintModel(session, session.model, true); } return; } + if (envelope.pageKey !== session.id || envelope.generation !== session.generation) { return; } + const operation = { key: session.id, projectRoot: session.projectRoot, generation: session.generation }; + const current = () => operationMatches(operation, { key: session.id ?? "", projectRoot: session.projectRoot, generation: session.generation }); switch (message.type) { - case "openUrl": { - // `decodeDetailMessage` already restricted this to https. - await openExternal(session, message.url); + case "selectProject": { + const root = await session.deps.chooseProject?.(); + if (root !== undefined && current()) { + session.projectRoot = root; session.generation++; session.result = undefined; + if (session.model) { paintModel(session, { ...session.model, generation: session.generation, projectRoot: root, projectState: undefined, installed: undefined, loading: true, blockedReason: t("Reading package details…"), result: undefined }); } + await render(session, session.id); + } + return; + } + case "showOutput": session.deps.output.show(true); return; + case "openManifest": + if (session.projectRoot) { await vscode.window.showTextDocument(vscode.Uri.file(path.join(session.projectRoot, "mcpp.toml"))); } + return; + case "retry": + if (session.result?.state === "error") { session.result = undefined; } + await render(session, session.id); return; + case "openDependency": + if (session.model?.dependencies.some((dependency) => dependency.key === message.key)) { await open(session, message.key); } + return; + case "openFile": { + if (!session.model?.snippets.some((snippet) => snippet.fileKey === message.key)) { return; } + if (message.key.startsWith(`${EXAMPLE_SCHEME}:`)) { await vscode.window.showTextDocument(vscode.Uri.parse(message.key)); } return; } case "copy": { - // The command preview and the usage lines: both are text a reader pastes - // somewhere else, and a click that answers with nothing looks like a dead - // button (the lesson `openExternal` learned in §20.2). - try { - await vscode.env.clipboard.writeText(message.text); - postResult(session, { state: "ok", message: t("Copied to the clipboard.") }); - } catch (error) { - session.deps.output.appendLine( - `mcpp library: copying to the clipboard failed: ${error instanceof Error ? error.message : String(error)}`, - ); - postResult(session, { state: "error", message: t("Could not write the clipboard.") }); - } + let result: string; + try { await vscode.env.clipboard.writeText(message.text); result = t("Copied"); } + catch { result = t("Copy failed"); } + if (current()) { void session.panel?.webview.postMessage({ type: "copyResult", key: operation.key, generation: operation.generation, token: message.token, message: result }); } + return; + } + case "openUrl": { + // Only links in this package's model can ask the host to open a browser. + if (message.url !== session.model?.repo && message.url !== session.model?.indexUrl) { return; } + let opened = false; + try { opened = await vscode.env.openExternal(vscode.Uri.parse(message.url)); } catch { /* report below */ } + let copied = false; + if (!opened) { try { await vscode.env.clipboard.writeText(message.url); copied = true; } catch { /* accurate feedback below */ } } + if (current()) { void session.panel?.webview.postMessage({ type: "linkResult", key: operation.key, generation: operation.generation, + message: opened ? t("Opened in your browser.") : copied ? t("Could not open the browser. Link copied to clipboard.") : t("Could not open the browser or copy the link: {0}", message.url) }); } return; } case "add": { - if (session.busy || session.id === undefined) { - return; - } + const model = session.model; + if (session.busy || !model || model.blockedReason || model.preview || !model.currentVersions.includes(message.version)) { return; } + const state = model.dependencyGroups?.[message.dev ? "dev" : "normal"] ?? model.projectState; + const other = model.dependencyGroups?.[message.dev ? "normal" : "dev"]; + if (state?.ambiguous || state?.declared && state.sourceType !== "registry" || !state?.declared && other?.declared) { return; } session.busy = true; - let result: DetailResult; + session.result = { state: "pending", message: t("Adding dependency…") }; + paintModel(session, { ...model, busy: true, result: session.result }); try { - const outcome = await addDependency( - { - mcppExecutable: session.deps.mcppExecutable, - projectRoot: session.deps.projectRoot, - output: session.deps.output, - isTrusted: session.deps.isTrusted, - }, - { id: session.id, version: message.version, dev: message.dev }, - ); - result = { state: outcome.ok ? "ok" : "error", message: outcome.message }; - if (outcome.ok) { - session.deps.onDependenciesChanged?.(); + const executable = session.deps.mcppExecutable(operation.projectRoot); + const snapshot = await loadSnapshot({ projectRoot: operation.projectRoot }); + const declarations = readProjectDeclarations(operation.projectRoot ? readTextTolerantly(path.join(operation.projectRoot, "mcpp.toml")) : ""); + const catalog = snapshot.entries.map((entry) => entry.id); + const fresh = projectDependencyState(model.id, declarations, [], catalog, message.dev ? "dev" : "normal"); + const otherGroup = projectDependencyState(model.id, declarations, [], catalog, message.dev ? "normal" : "dev"); + if (fresh.ambiguous || fresh.declared && fresh.sourceType !== "registry" || !fresh.declared && otherGroup.declared) { + if (current()) { session.result = { state: "error", message: t("The dependency declaration changed. Review mcpp.toml before adding it.") }; } + return; + } + const outcome = await addDependency({ + mcppExecutable: () => executable, + projectRoot: () => operation.projectRoot, + isTrusted: session.deps.isTrusted, + output: session.deps.output, + quiet: true, + }, { id: model.id, version: message.version, dev: message.dev }); + if (outcome.ok) { session.deps.onDependenciesChanged?.(); } + if (current() && session.panel) { + session.result = { state: outcome.ok ? "ok" : "error", message: outcome.message }; + } else { + void (outcome.ok ? vscode.window.showInformationMessage(outcome.message) : vscode.window.showErrorMessage(outcome.message)); } + } catch (error) { + session.deps.output.appendLine(String(error)); + if (current()) { session.result = { state: "error", message: t("Could not add the dependency. See output for details.") }; } } finally { session.busy = false; + if (session.panel && session.id) { await render(session, session.id); } } - if (session.panel === undefined) { - return; - } - postResult(session, result, result.state === "ok" ? message.version : undefined); return; } - default: - return; } } -/** - * Open a link, and say what happened. - * - * This used to be `void vscode.env.openExternal(…)`: the boolean it resolves to - * was dropped, so a host with no browser (or no way to reach one) answered a - * click with nothing at all — indistinguishable from a dead button. Now the page - * is told either way, a failure is copied to the clipboard so the click is still - * worth something, and the output channel keeps a record. - */ -async function openExternal(session: DetailSession, url: string): Promise { - let opened = false; - try { - opened = await vscode.env.openExternal(vscode.Uri.parse(url)); - } catch (error) { - session.deps.output?.appendLine( - `mcpp library: opening ${url} failed: ${error instanceof Error ? error.message : String(error)}`, - ); - } - if (opened) { - postResult(session, { state: "ok", message: t("Opened {0} in your browser.", url) }); - return; - } - session.deps.output?.appendLine(`mcpp library: VS Code could not open ${url}; copying it instead.`); - try { - await vscode.env.clipboard.writeText(url); - } catch { - // A clipboard that refuses is not worth a second error. +function paintModel(session: DetailSession, model: DetailModel, replay = false): void { + const panel = session.panel; + if (!panel) { return; } + session.model = model; + const html = renderDetailHtml(model, session.webviewDocument.assets(vscode.Uri.joinPath(session.context.extensionUri, MEDIA_DIRECTORY), panel.webview)); + if (session.lastHtml === html && !replay) { return; } + session.lastHtml = html; + if (!session.painted && !replay) { + session.webviewDocument.paint(panel.webview, html); session.painted = true; + } else { + void panel.webview.postMessage({ type: "detailUpdate", html, state: detailClientState(model) }); } - postResult(session, { - state: "error", - message: t("VS Code could not open {0}. The link is on your clipboard.", url), - }); -} - -/** - * The page's status line, in the same shape the add flow uses. - * - * `added` tells the page that the project now depends on that version, so it can - * move its "added" marker and re-label the button without rebuilding the - * document — which would throw away the reader's scroll position and their - * version selection, the one thing running `mcpp add` must not do. - */ -function postResult(session: DetailSession, result: DetailResult, added?: string): void { - void session.panel?.webview.postMessage({ - type: "result", - result, - ...(added === undefined ? {} : { added: { version: added } }), - }); } async function render(session: DetailSession, id: string): Promise { const panel = session.panel; - if (panel === undefined) { - return; - } - const model = await buildModel(session, id); - if (session.panel !== panel || session.id !== id) { - return; + const generation = session.generation; + const request = session.renderRequest = (session.renderRequest ?? 0) + 1; + const root = session.projectRoot; + if (!panel) { return; } + let model: DetailModel; + try { model = await buildModel(session, id, request); } + catch (error) { + session.deps.output.appendLine(String(error)); + model = emptyModel(path.basename(id, ".lua"), labels(), t("Could not read package details. See output for details.")); + model.blockedReason = model.parseNotice; + model.result = { state: "error", message: model.parseNotice ?? "" }; } - const html = renderDetailHtml( - model, - session.webviewDocument.assets( - vscode.Uri.joinPath(session.context.extensionUri, MEDIA_DIRECTORY), - panel.webview, - ), - ); - session.webviewDocument.paint(panel.webview, html); + if (session.panel !== panel || session.id !== id || generation !== session.generation || request !== session.renderRequest || root !== session.projectRoot) { return; } + paintModel(session, { ...model, key: id, generation, busy: session.busy, result: session.result ?? model.result }); } -async function buildModel(session: DetailSession, id: string): Promise { - const projectRoot = session.deps.projectRoot(); +async function buildModel(session: DetailSession, id: string, request: number): Promise { + const projectRoot = session.projectRoot; + const generation = session.generation; const snapshot = await loadSnapshot(projectRoot === undefined ? {} : { projectRoot }); - const entry = snapshot.entries.find((candidate) => candidate.id === id); + const entry = snapshot.entries.find((candidate) => candidate.file === id || candidate.id === id); // The root the descriptor lives under, matched by path: two roots may share a // directory name, and the site link belongs to the one that holds the file. - const root = entry === undefined ? undefined : snapshot.roots.find((candidate) => entry.file.startsWith(candidate.path)); + const root = entry === undefined ? undefined : snapshot.roots.find((candidate) => { const relative = path.relative(candidate.path, entry.file); return relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative); }); const ui = labels(); if (entry === undefined) { - return emptyModel(id, ui, t("This package is not in the local index any more.")); + const preview = session.preview; + const model = emptyModel(preview?.id ?? path.basename(id, ".lua"), ui, preview ? t("This is a search preview. Set an index path containing this package to read its complete details.") : t("This package is not in the local index any more.")); + model.preview = preview !== undefined; + model.previewVersion = preview?.version; + model.description = preview?.description; + model.registry = preview?.source ?? ""; + model.projectRoot = projectRoot; + model.blockedReason = preview ? t("Search previews cannot be added. Open a complete local descriptor first.") : t("The package descriptor is missing. Reread the local index."); + return model; } - const text = cachedDescriptorText(id) ?? (await readDescriptorText(entry.file)) ?? ""; + const text = cachedDescriptorText(entry.file) ?? (await readDescriptorText(entry.file)) ?? ""; const platform = platformKey(process.platform); // Keyed by the index revision as well as the path, so a refreshed index is not // answered from a parse of the previous one. - const cacheKey = `${snapshot.revision}\u0000${entry.file}`; + const cacheKey = `${snapshot.revision}\u0000${entry.file}\u0000${session.deps.isTrusted()}\u0000${session.deps.mcppExecutable(projectRoot)}\u0000${projectRoot ?? ""}`; let info = parsed.get(cacheKey); if (!parsed.has(cacheKey)) { - info = await readXpkg(session, entry); - parsed.set(cacheKey, info); + if (session.id === id && session.generation === generation && session.renderRequest === request && session.model?.loading) { + const lightweight: DetailModel = { + ...emptyModel(entry.id, ui, t("Reading package details…")), + key: id, generation, projectRoot, platform: platform ?? process.platform, + description: entry.description, registry: entry.registry, surface: entry.surface, surfaces: entry.surfaces, + licenses: entry.licenses, repo: entry.repo, badges: badgesOf(entry), + currentVersions: entry.versions[platform ?? ""] ?? [], latest: entry.version, + versions: versionGroups(entry.versions, platform).map((group) => ({ ...group, current: group.platform === platform })), + loading: true, blockedReason: t("Reading package details…"), dataSource: dataSource(entry, snapshot.roots.length), + }; + paintModel(session, lightweight); + } + info = await readXpkg(session, entry, projectRoot); + if (info !== undefined) { parsed.set(cacheKey, info); } + while (parsed.size > 100) { parsed.delete(parsed.keys().next().value!); } } const versions = info === undefined ? entry.versions : info.versions; @@ -308,44 +385,69 @@ async function buildModel(session: DetailSession, id: string): Promise ({ + file: file.path, startLine: 1, usageLine: 0, lines: file.text.split(/\r?\n/).slice(0, 80), + fileKey: session.exampleDocuments.capture(file), + })); + // Only verified lines from real example source are copyable. const realUsage = usageLinesFor(exampleFiles, entry.id); - const usage = realUsage.length > 0 ? realUsage : syntheticUsageLines(mergeSurfaces(info, text), entry.id); + const usage = realUsage; // The lock answers what a build actually resolved for each declared edge — // the same matching rule `installedFor` uses for this package itself. - const lock = lockPackageVersions(readInstalledLock(session)); + const lockText = projectRoot ? readTextTolerantly(path.join(projectRoot, "mcpp.lock")) : ""; + const manifestText = projectRoot ? readTextTolerantly(path.join(projectRoot, "mcpp.toml")) : ""; + if (projectRoot) { session.deps.onProjectFilesRead?.(projectRoot, manifestText, lockText); } + const lock = lockPackageVersions(lockText); + const declarations = readProjectDeclarations(manifestText); + const catalog = snapshot.entries.map((entry) => entry.id); + const dependencyGroups = { + normal: projectDependencyState(entry.id, declarations, lock, catalog, "normal"), + dev: projectDependencyState(entry.id, declarations, [], catalog, "dev"), + build: projectDependencyState(entry.id, declarations, [], catalog, "build"), + }; + const dependencyKind = dependencyGroups.normal.declared ? "normal" : dependencyGroups.dev.declared ? "dev" : dependencyGroups.build.declared ? "build" : "normal"; + const state = dependencyGroups[dependencyKind]; const dependencies = descriptorDependencies(text).map((dependency) => { - const short = dependency.id.slice(dependency.id.lastIndexOf(".") + 1); - const resolved = lock.find((entry) => entry.id === dependency.id || entry.id === short)?.version; - return resolved === undefined ? { ...dependency } : { ...dependency, resolved }; + const resolved = lock.find((entry) => entry.id === dependency.id)?.version; + const local = snapshot.entries.find((entry) => entry.id === dependency.id); + return { ...dependency, ...(resolved ? { resolved } : {}), ...(local ? { key: local.file } : {}) }; }); const model: DetailModel = { ui, + projectRoot, + manifestAvailable: !!projectRoot && existsSync(path.join(projectRoot, "mcpp.toml")), + platform: platform ?? process.platform, + projectState: state, + dependencyGroups, + dependencyKind, + blockedReason: !session.deps.isTrusted() ? t("Trust this workspace to run mcpp and add dependencies.") + : !projectRoot || !existsSync(path.join(projectRoot, "mcpp.toml")) ? t("Select an mcpp project before adding this library.") + : platform === undefined ? t("The current environment platform is not recognized by this index.") + : latest === undefined ? info === undefined ? t("Version availability could not be confirmed. Retry reading this descriptor.") : t("No version is published for the current environment platform.") + : undefined, + versionNotice: info === undefined ? t("Versions are from descriptor text; mcpp will confirm availability when adding.") : undefined, id: entry.id, name: entry.name, ...(entry.description === undefined ? {} : { description: entry.description }), licenses: entry.licenses, ...(entry.repo === undefined ? {} : { repo: entry.repo }), registry: entry.registry, - ...(entry.surface === undefined ? {} : { surface: entry.surface }), - surfaces: entry.surfaces, + ...(mergeSurfaces(info, text)[0] === undefined ? {} : { surface: mergeSurfaces(info, text)[0] }), + surfaces: mergeSurfaces(info, text), badges: badgesOf(entry), versions: groups, currentVersions: sortVersions(currentVersions), ...(latest === undefined ? {} : { latest }), - // §22: the page finally learns what the project already has. Without this - // the button said "Add" to a package mcpp.toml listed all along. - ...readInstalled(session, entry.id), ...(info?.standard === undefined ? {} : { standard: info.standard }), dependencies, includeDirs: info?.includeDirs ?? [], targets: (info?.targets ?? []).map((target) => target.name ?? "").filter((name) => name.length > 0), snippets, - ...(entry.example === undefined ? {} : { exampleProject: entry.example.project }), + ...(bundled ? { exampleProject: bundled.project, exampleProvenance: t("Bundled official index tests · commit {0}", bundled.commit.slice(0, 12)) } : entry.example ? { exampleProject: entry.example.project } : {}), usage, // One discreet link, and only when this root really is the index that // publishes those package pages (see `IndexRoot.site`). @@ -367,13 +469,13 @@ async function buildModel(session: DetailSession, id: string): Promise { +async function readXpkg(session: DetailSession, entry: LibraryEntry, projectRoot?: string): Promise { // `mcpp.path` is resource-scoped, so an untrusted workspace must not name // the program: the refusal degrades to the descriptor's own text. const result = await vscode.window.withProgress( { location: vscode.ProgressLocation.Window, title: t("Reading {0}…", entry.id) }, () => - runMcpp(session.deps.isTrusted(), session.deps.mcppExecutable(), ["xpkg", "parse", entry.file, "--json"], session.deps.projectRoot(), { + runMcpp(session.deps.isTrusted(), session.deps.mcppExecutable(projectRoot), ["xpkg", "parse", entry.file, "--json"], projectRoot, { timeoutMs: PARSE_TIMEOUT_MS, maxBufferMiB: read("mcpp.runtime.maxOutputMiB"), }), @@ -424,42 +526,41 @@ function emptyModel(id: string, ui: Record, notice: string): Det }; } -/** - * The workspace's own answer about one package (§20.1, wired in §22): - * `mcpp.toml` first, `mcpp.lock` second, both read tolerantly — a missing or - * unreadable file is simply "not installed", never a broken page. The spread - * sets `installed` only when there is one. - */ -function readInstalled(session: DetailSession, id: string): { installed?: DetailInstalled } { - const root = session.deps.projectRoot(); - if (root === undefined) { - return {}; - } - const toml = readTextTolerantly(path.join(root, "mcpp.toml")); - const lock = readTextTolerantly(path.join(root, "mcpp.lock")); - const installed = installedFor(id, toml, lock); - return installed === undefined ? {} : { installed }; -} - -/** An unreadable or missing file reads as empty text; the view degrades, not breaks. */ function readTextTolerantly(file: string): string { - try { - return readFileSync(file, "utf8"); - } catch { - return ""; - } -} - -/** The workspace's `mcpp.lock` text, empty when there is none to read. */ -function readInstalledLock(session: DetailSession): string { - const root = session.deps.projectRoot(); - return root === undefined ? "" : readTextTolerantly(path.join(root, "mcpp.lock")); + try { return readFileSync(file, "utf8"); } catch { return ""; } } /** Every visible string, resolved once per model. */ function labels(): Record { return { [DETAIL_UI.htmlLang]: htmlLanguage(), + [DETAIL_UI.platforms]: t("Platforms and versions"), + [DETAIL_UI.kind]: t("Dependency type"), + [DETAIL_UI.kindNormal]: t("Project dependency"), + [DETAIL_UI.kindDev]: t("Development dependency"), + [DETAIL_UI.kindBuild]: t("Build dependency"), + [DETAIL_UI.addDevAction]: t("Add development dependency"), + [DETAIL_UI.buildHint]: t("Build dependencies are used by the build script. Copy this entry into mcpp.toml; mcpp add does not support this group yet."), + [DETAIL_UI.moveHint]: t("Changing this declaration requires a manifest edit. Copy the entry and update its dependency group in mcpp.toml."), + [DETAIL_UI.chooseProject]: t("Choose project"), + [DETAIL_UI.platform]: t("Environment platform"), + [DETAIL_UI.version]: t("Version"), + [DETAIL_UI.otherPlatforms]: t("Other platforms (read only)"), + [DETAIL_UI.declared]: t("Declared"), + [DETAIL_UI.locked]: t("Resolved in lockfile"), + [DETAIL_UI.sourceDependency]: t("Source dependency"), + [DETAIL_UI.unknownUsage]: t("No verified import or header path is available locally. See the repository or index site for usage."), + [DETAIL_UI.usageSource]: t("From the index's example source"), + [DETAIL_UI.source]: t("Source and diagnostics"), + [DETAIL_UI.loading]: t("Reading package details…"), + [DETAIL_UI.pending]: t("Adding dependency…"), + [DETAIL_UI.groupChange]: t("Changing dependency groups is not supported here. Edit mcpp.toml to move the declaration."), + [DETAIL_UI.output]: t("Show output"), + [DETAIL_UI.retry]: t("Retry reading details"), + [DETAIL_UI.openManifest]: t("Open mcpp.toml"), + [DETAIL_UI.openFile]: t("Source"), + [DETAIL_UI.readOnlySource]: t("Open read-only source"), + [DETAIL_UI.preview]: t("Search preview: only the fields returned by mcpp search are available."), [DETAIL_UI.title]: t("Library package {0}"), [DETAIL_UI.overview]: t("Build shape"), [DETAIL_UI.license]: t("License"), @@ -477,23 +578,23 @@ function labels(): Record { [DETAIL_UI.dependencies]: t("Dependencies"), [DETAIL_UI.dependenciesNone]: t("This descriptor declares no dependencies."), [DETAIL_UI.dependenciesHint]: t( - "What the descriptor declares. The resolved version lives in a project's mcpp.lock, not here.", + "Descriptor-level dependencies; the selected version may differ. Resolved values refer to this project's lockfile.", ), [DETAIL_UI.resolved]: t("resolved {0}"), [DETAIL_UI.code]: t("Example code"), [DETAIL_UI.codeNone]: t("This package has no test project in the index, so there is no example to show."), [DETAIL_UI.codeSource]: t("{0} · line {1}"), [DETAIL_UI.codeProject]: t("Example project: {0} — built and run by the index's CI, not written for this page."), - [DETAIL_UI.add]: t("Add to mcpp.toml"), + [DETAIL_UI.add]: t("Add dependency"), [DETAIL_UI.addDev]: t("dev dependency"), [DETAIL_UI.addLatest]: t("The version is required: mcpp accepts an exact version only."), [DETAIL_UI.switchTo]: t("Switch to {0}"), - [DETAIL_UI.alreadyAdded]: t("Already added"), + [DETAIL_UI.alreadyAdded]: t("Already declared"), [DETAIL_UI.installed]: t("added"), [DETAIL_UI.opening]: t("Opening {0}…"), [DETAIL_UI.addNoVersion]: t("This index publishes no version for this platform, so there is nothing to add."), [DETAIL_UI.command]: t("Command"), - [DETAIL_UI.usage]: t("Bring it into your code"), + [DETAIL_UI.usage]: t("Usage"), [DETAIL_UI.copy]: t("Copy"), [DETAIL_UI.copied]: t("Copied to the clipboard."), [DETAIL_UI.copying]: t("Copying…"), diff --git a/src/library/examples.ts b/src/library/examples.ts new file mode 100644 index 0000000..71a3c00 --- /dev/null +++ b/src/library/examples.ts @@ -0,0 +1,22 @@ +import snapshot from "../../data/library-examples.json"; +import { ReadOnlyDocuments } from "../webview/readOnlyDocuments"; +import { exampleCatalog, type CodeFile } from "./indexModel"; + +const catalog = exampleCatalog(snapshot.projects.map((project) => ({ + project: project.project, text: project.text, sources: project.files.map((file) => file.path), +}))); +const files = new Map(snapshot.projects.flatMap((project) => project.files.map((file) => [file.path, file.text] as const))); + +/** Official-index fallback only. Local checkouts use their own current tests. */ +export function bundledExample(id: string): { project: string; files: CodeFile[]; commit: string } | undefined { + const ref = catalog.get(id); + return ref ? { project: ref.project, commit: snapshot.commit, files: ref.paths.map((path) => ({ path, text: files.get(path)! })) } : undefined; +} + +export function bundledExampleText(path: string): string | undefined { return files.get(path.replace(/^\//, "")); } +export const EXAMPLE_SCHEME = "mcpp-example"; + +/** Immutable virtual documents keep local and bundled index sources equally read-only. */ +export class ExampleDocuments extends ReadOnlyDocuments { + constructor(captured?: (uri: string) => void) { super(EXAMPLE_SCHEME, captured); } +} diff --git a/src/library/indexLocator.ts b/src/library/indexLocator.ts index a29770a..afa6291 100644 --- a/src/library/indexLocator.ts +++ b/src/library/indexLocator.ts @@ -1,33 +1,7 @@ -/** - * Where the index lives, and how it is read **cheaply**. - * - * The catalog is a directory of Lua descriptors: - * `/.mcpp/registry/data//pkgs//.lua`. Three - * registries are installed on the reference machine (`mcpplibs` with 239 - * descriptors, `xim-pkgindex`, `xim-pkgindex-local`), and `mcpp index status` - * prints a table of them — which is deliberately **not** parsed: `--format json` - * is an unknown option there, and a second human-output parser is exactly what - * this project forbids. Globbing the data directory under `` gives the - * same answer without parsing anything. - * - * `` is `$MCPP_HOME`, then `~/.mcpp` — every one of them that holds a data - * directory — and when none does, whatever `mcpp self env --format json` - * reports, which is a machine shape and therefore allowed to be read. - * - * Two budgets shape this file: - * - * - **No process per package.** The list is read from the descriptor text - * (`src/library/indexModel.ts`); `mcpp xpkg parse --json` runs on demand, from - * the detail panel, never here. - * - **One read per index revision.** A snapshot is cached and invalidated by a - * cheap revision key (the `pkgs` directory's mtime, the `.mcpp-index-updated` - * marker and the descriptor count), so re-rendering the view after a filter - * change costs a few stats, not 239 file reads. - * - * A missing index is **not** an error: `locateIndexRoots()` returns `[]` and the - * caller renders the message this module hands it. +/** Local package discovery. Official indexes are separate from the xlings tool registry. + * Descriptor contents are cached independently from the project's dependency state. */ - +import { createHash } from "node:crypto"; import { promises as fs } from "node:fs"; import * as os from "node:os"; import * as path from "node:path"; @@ -35,10 +9,10 @@ import * as vscode from "vscode"; import { runMcpp } from "../cli/process"; import { read } from "../config/access"; +import { projectDependencyState, readProjectDeclarations } from "./projectState"; import { descriptorEntry, descriptorId, - declaredDependencies, exampleCatalog, openkalFacetFor, parseDescriptorLua, @@ -68,6 +42,8 @@ export const INDEX_SITE = "https://mcpplibs.github.io/mcpp-index/packages"; export interface IndexRoot { /** The directory name, e.g. `mcpplibs`. */ registry: string; + kind: "official" | "custom"; + updatedAt?: number; /** The index root: it contains `pkgs`, and may contain `tests/` and `.xpkgindex/`. */ path: string; /** `/pkgs`. */ @@ -124,164 +100,83 @@ async function isFile(target: string): Promise { } /** One index root, or `undefined` when the directory is not one. */ -async function rootAt(directory: string): Promise { +async function rootAt(directory: string, official = false): Promise { const pkgs = path.join(directory, "pkgs"); if (!(await isDirectory(pkgs))) { return undefined; } + directory = await fs.realpath(directory); const registry = path.basename(directory); + const updated = await statSafe(path.join(directory, ".mcpp-index-updated")); const generator = await isFile(path.join(directory, ".xpkgindex", "plugins", "mcpp.py")); return { registry, + kind: official ? "official" : "custom", + ...(updated === undefined ? {} : { updatedAt: updated.mtimeMs }), path: directory, - pkgs, + pkgs: path.join(directory, "pkgs"), hasExamples: await isDirectory(path.join(directory, "tests", "examples")), hasOpenkal: await isFile(path.join(directory, ".xpkgindex", "openkal-compat.json")), - ...(registry === "mcpplibs" || generator ? { site: INDEX_SITE } : {}), + ...(official || generator ? { site: INDEX_SITE } : {}), }; } -/** - * The index roots to read. - * - * `mcpp.library.indexPath` wins when the user set it — it may name one index - * root (a directory with `pkgs/`), a `pkgs` directory itself, or a whole - * `/.mcpp/registry/data` directory of registries. With no setting, the - * default glob is the data directory under each known mcpp home. - * - * **Finding ``.** Two are tried, in order: `$MCPP_HOME` (the variable mcpp - * itself honours) and `~/.mcpp`. Both are listed when both hold something, and - * the view's footer names the registries it read, so a stale second home shows - * up as an extra source rather than as a wrong answer. When *neither* has a - * `registry/data` with anything in it, mcpp is asked directly — `mcpp self env - * --format json` reports `mcppHome`, which is the only authoritative answer for - * an install in a place nothing can guess. That probe costs one process **per - * session** and only runs when the cheap globs came up empty, so the ordinary - * machine never pays for it; it is also skipped in an untrusted workspace, - * because `mcpp.path` is a resource-scoped setting and a workspace must not - * choose a binary to run. - * - * `[]` means "no index found"; the caller turns that into the message rather - * than into an error, because a machine without the index is a normal machine. - * - * (`locateIndexRoots` is kept as an alias: the name reads better at the call - * site, the exported name is the one `extension.ts` uses.) - */ -export async function readIndexRoots(): Promise { +/** Explicit paths never silently fall back. Only the official library source is auto-discovered. */ +export async function readIndexRoots(projectRoot?: string): Promise { const configured = read("mcpp.library.indexPath"); - const candidates: string[] = []; - if (typeof configured === "string" && configured.trim().length > 0) { - const configured_path = path.resolve(expandHome(configured.trim())); - // A `pkgs` directory was named directly. - if (path.basename(configured_path) === "pkgs" && (await isDirectory(configured_path))) { - candidates.push(path.dirname(configured_path)); - } else { - const own = await rootAt(configured_path); - if (own !== undefined) { - candidates.push(own.path); - } else { - // A data directory: every registry inside it. - for (const entry of await readdirSafe(configured_path)) { - candidates.push(path.join(configured_path, entry)); - } - } - } - } else { - for (const data of await defaultDataDirectories()) { - for (const entry of await readdirSafe(data)) { - candidates.push(path.join(data, entry)); - } - } - } + return discoverIndexRoots(configured, configured.trim() ? path.join(os.homedir(), ".mcpp") : await activeHome(projectRoot)); +} - const roots: IndexRoot[] = []; - for (const candidate of candidates) { - const root = await rootAt(candidate); - if (root !== undefined && !roots.some((seen) => seen.path === root.path)) { - roots.push(root); +/** Filesystem seam used by the extension and fixture-based tests. */ +export async function discoverIndexRoots(configured: string, home: string): Promise { + if (configured.trim()) { + const target = path.resolve(expandHome(configured.trim())); + const own = await rootAt(path.basename(target) === "pkgs" ? path.dirname(target) : target); + const roots = own === undefined + ? (await Promise.all((await readdirSafe(target)).sort().map((name) => rootAt(path.join(target, name))))) + .filter((root): root is IndexRoot => root !== undefined) + : [own]; + if (roots.length === 0) { + throw new Error(`No package index (pkgs/) at ${target}`); } + return roots.filter((root, index) => roots.findIndex((other) => other.path === root.path) === index); + } + for (const directory of [path.join(home, "indices", "mcpplibs"), path.join(home, "registry", "data", "mcpplibs")]) { + const root = await rootAt(directory, true); + if (root !== undefined) { return [root]; } } - return roots.sort((a, b) => (a.registry < b.registry ? -1 : a.registry > b.registry ? 1 : 0)); + return []; } -/** Set once per session, so `mcpp self env` runs at most once. */ -let probedHome: string | undefined; -let probeAttempted = false; +let homeProbe: { key: string; promise: Promise } | undefined; -/** The homes mcpp may have used, most specific first, without duplicates. */ -function candidateHomes(): string[] { - const homes: string[] = []; - const fromEnvironment = process.env.MCPP_HOME?.trim(); - if (fromEnvironment !== undefined && fromEnvironment.length > 0) { - homes.push(fromEnvironment); - } - homes.push(path.join(os.homedir(), ".mcpp")); - if (probedHome !== undefined) { - homes.push(probedHome); - } - return [...new Set(homes)]; +/** CLI also supports self-contained installs: ask it once rather than merge unrelated homes. */ +async function activeHome(projectRoot?: string): Promise { + const explicit = process.env.MCPP_HOME?.trim(); + if (explicit) { return path.resolve(expandHome(explicit)); } + return (await mcppHomeFromCli(projectRoot)) ?? path.join(os.homedir(), ".mcpp"); } -/** - * The `/registry/data` directories worth listing. - * - * The cheap answer first: a data directory that already holds something is the - * answer, and no process is started. Only when all of them are missing or empty - * is `mcpp self env` asked where its home is — and its answer is picked up by - * re-reading the candidate list, because the probe is what adds the home to it. - */ -async function defaultDataDirectories(): Promise { - const candidates = (): string[] => candidateHomes().map((home) => path.join(home, "registry", "data")); - const present: string[] = []; - for (const data of candidates()) { - if ((await readdirSafe(data)).length > 0) { - present.push(data); - } - } - if (present.length > 0) { - return present; - } - await mcppHomeFromCli(); - return [...new Set(candidates())]; +export function invalidateIndexCache(): void { + cache = undefined; + homeProbe = undefined; } -/** - * `mcpp self env --format json`, for the one field that says where the index is. - * - * It runs at most once per session and never in an untrusted workspace. A - * missing or failing mcpp is not an error here: the caller falls back to the - * directories it already has, and the view says "no index" the way it does when - * there is none. - */ -async function mcppHomeFromCli(): Promise { - if (probeAttempted) { - return probedHome; - } - probeAttempted = true; - const executable = read("mcpp.path").trim(); - // `mcpp.path` is resource-scoped, so the probe goes through the trust-gated - // seam; a refusal is the same "no answer" as a failing mcpp. - const result = await runMcpp( - vscode.workspace.isTrusted, - executable.length === 0 ? "mcpp" : executable, - ["self", "env", "--format", "json"], - undefined, - { timeoutMs: SELF_ENV_TIMEOUT_MS, maxBufferMiB: 1 }, - ); - if (result === undefined || result.exitCode !== 0) { - return undefined; - } - const env = parseSelfEnv(result.stdout); - if (env === undefined) { - return undefined; - } - if (env.mcppHome !== undefined) { - probedHome = env.mcppHome; - } else if (env.registry !== undefined) { - // `registry` is `/registry`; the home is what the other paths hang off. - probedHome = path.dirname(env.registry); - } - return probedHome; +/** Share concurrent probes, with separate answers for different configured executables/projects. */ +async function mcppHomeFromCli(projectRoot?: string): Promise { + const resource = projectRoot === undefined ? undefined : vscode.Uri.file(projectRoot); + const executable = read("mcpp.path", resource).trim() || "mcpp"; + const key = `${executable}\u0000${projectRoot ?? ""}\u0000${vscode.workspace.isTrusted}`; + if (homeProbe?.key === key) { return homeProbe.promise; } + const promise = (async () => { + const result = await runMcpp(vscode.workspace.isTrusted, executable, ["self", "env", "--format", "json"], projectRoot, + { timeoutMs: SELF_ENV_TIMEOUT_MS, maxBufferMiB: 1 }); + if (result === undefined || result.exitCode !== 0) { return undefined; } + const env = parseSelfEnv(result.stdout); + return env?.mcppHome ?? (env?.registry === undefined ? undefined : path.dirname(env.registry)); + })(); + homeProbe = { key, promise }; + return promise; } export { readIndexRoots as locateIndexRoots }; @@ -324,23 +219,15 @@ async function descriptorFiles(pkgs: string): Promise { return out.sort(); } -/** - * A cheap key that changes when the index does. - * - * The `pkgs` directory's own mtime catches an added or removed letter - * directory; `.mcpp-index-updated` is written whenever mcpp refreshes the index, - * which catches a changed descriptor body. The descriptor count is included so a - * tree that stops being updated still costs one full read when its size changes. - */ +/** Include source identity and every descriptor stat, including checkout edits without a marker. */ async function revisionOf(roots: readonly IndexRoot[]): Promise { const parts: string[] = []; for (const root of roots) { - const pkgs = await statSafe(root.pkgs); - const marker = await statSafe(path.join(root.path, ".mcpp-index-updated")); - const letters = await readdirSafe(root.pkgs); - parts.push(`${root.registry}:${pkgs?.mtimeMs ?? 0}:${marker?.mtimeMs ?? 0}:${letters.length}`); + const files = await descriptorFiles(root.pkgs); + const stats = await Promise.all(files.map(async (file) => `${file}:${JSON.stringify(await statSafe(file))}`)); + parts.push(`${root.path}:${root.kind}:${root.updatedAt ?? ""}:${stats.join(";")}`); } - return parts.join("|"); + return createHash("sha256").update(parts.join("|")).digest("hex"); } async function statSafe(target: string): Promise<{ mtimeMs: number; size: number } | undefined> { @@ -416,17 +303,14 @@ async function readOpenkal(roots: readonly IndexRoot[]): Promise> { - if (projectRoot === undefined) { - return new Set(); - } - try { - const text = await fs.readFile(path.join(projectRoot, "mcpp.toml"), "utf8"); - return new Set(declaredDependencies(text)); - } catch { - return new Set(); - } +/** Project overlay is always fresh and never changes the descriptor cache. */ +async function withProject(snapshot: LibrarySnapshot, projectRoot?: string): Promise { + const text = projectRoot === undefined ? "" : await fs.readFile(path.join(projectRoot, "mcpp.toml"), "utf8").catch(() => ""); + const declarations = readProjectDeclarations(text); + const ids = snapshot.entries.map((entry) => entry.id); + return { ...snapshot, entries: snapshot.entries.map((entry) => ({ + ...entry, added: (["normal", "dev", "build"] as const).some((kind) => projectDependencyState(entry.id, declarations, [], ids, kind).declared), + })) }; } interface Cache { @@ -441,15 +325,14 @@ let cache: Cache | undefined; /** * The list, read from disk only when the revision changed. * - * `projectRoot` is the workspace folder whose `mcpp.toml` decides the "already - * declared" state; it is part of the cache key, because switching workspaces - * changes the answer without changing the index. + * Only descriptor contents are cached. Project declarations are reapplied on + * every read, so disk writes and project switches cannot reuse old badges. */ export async function loadSnapshot(options: { projectRoot?: string; platform?: string } = {}): Promise { - const roots = await readIndexRoots(); - const revision = `${await revisionOf(roots)}|${options.projectRoot ?? ""}`; + const roots = await readIndexRoots(options.projectRoot); + const revision = `${await revisionOf(roots)}|${options.platform ?? platformKey(process.platform)}`; if (cache !== undefined && cache.revision === revision) { - return cache.snapshot; + return withProject(cache.snapshot, options.projectRoot); } if (roots.length === 0) { const empty: LibrarySnapshot = { entries: [], roots, revision }; @@ -458,21 +341,18 @@ export async function loadSnapshot(options: { projectRoot?: string; platform?: s } const platform = options.platform ?? platformKey(process.platform); - const added = await readAdded(options.projectRoot); const entries: LibraryEntry[] = []; const texts = new Map(); /** Example refs, keyed by package id, from every root that has examples. */ const exampleRefs = new Map(); for (const root of roots) { for (const [id, ref] of exampleCatalog(await readExamples(root))) { - if (!exampleRefs.has(id)) { - exampleRefs.set(id, ref); - } + exampleRefs.set(`${root.path}\u0000${id}`, ref); } } - const openkal = await readOpenkal(roots); for (const root of roots) { + const openkal = await readOpenkal([root]); for (const file of await descriptorFiles(root.pkgs)) { let text: string; try { @@ -485,7 +365,7 @@ export async function loadSnapshot(options: { projectRoot?: string; platform?: s // `descriptorEntry` decides the identity; the example and openkal lookups // below must use that same id, so it is computed the same way here. const id = descriptorId(fields, fileName).id; - const example = exampleRefs.get(id); + const example = exampleRefs.get(`${root.path}\u0000${id}`); const facet = openkalFacetFor(openkal, id); const entry = descriptorEntry({ fileName, @@ -493,19 +373,19 @@ export async function loadSnapshot(options: { projectRoot?: string; platform?: s file, text, platform, - added: added.has(id), + added: false, ...(example === undefined ? {} : { example }), ...(facet === undefined ? {} : { openkal: facet }), }); entries.push(entry); - texts.set(entry.id, text); + texts.set(entry.file, text); } } entries.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)); const snapshot: LibrarySnapshot = { entries, roots, revision }; cache = { revision, snapshot, texts }; - return snapshot; + return withProject(snapshot, options.projectRoot); } /** The descriptor text of one package, from the cache when possible. */ @@ -518,8 +398,8 @@ export async function readDescriptorText(file: string): Promise { const catalog = new Map(); + const priorities = new Map(); const sorted = [...inputs].sort((a, b) => (a.project < b.project ? -1 : a.project > b.project ? 1 : 0)); for (const input of sorted) { if (input.sources.length === 0) { @@ -949,8 +950,12 @@ export function exampleCatalog(inputs: readonly ExampleInput[]): Map; rows: LibraryRow[]; + selectedKey?: string; query: string; networkSearch: boolean; /** @@ -71,6 +74,9 @@ export interface LibraryModel { networkSearchSetting: string; /** The data source, in plain words, for the footer. */ dataSource: string; + sourceDetails?: string; + status?: string; + projectNotice?: string; /** `{0}` visible of `{1}` known, already localized; the header count uses it. */ countTemplate: string; /** Rows before filtering; the count line shows it against what is visible. */ @@ -112,6 +118,12 @@ export const LIBRARY_UI = { count: "library.count", open: "library.open", refresh: "library.refresh", + sources: "library.sources", + other: "library.other", + settings: "library.settings", + update: "library.update", + output: "library.output", + clear: "library.clear", } as const; /** One badge key's `ui` key, so the renderer has a single lookup table. */ @@ -124,23 +136,13 @@ const BADGE_KEY_UI: Readonly> = { "openkal-platform": LIBRARY_UI.badgeOpenkalPlatform, }; -/** - * What the document says to the host. - * - * There deliberately **no `ready` message**. The document is the data — every - * row, badge and count is already in it — so a "I have loaded" announcement can - * only invite the host to render the same thing again. It did exactly that, and - * because assigning `webview.html` reloads the document while every render mints - * a fresh CSP nonce, the page never matched the previous one: the view reloaded - * itself forever (flicker, unclickable rows, a pegged CPU). The host now also - * refuses to re-assign an identical document — both rules live in - * `src/webview/document.ts` (`WebviewDocument`) and `src/webview/render.ts` - * (`documentNeedsRender`) — so this cannot come back by accident. +/** A mounted handshake replays data in place after the initial document loads. + * The host never assigns webview.html in response, so it cannot create a reload loop. */ export type LibraryMessage = - | { type: "refresh" } + | { type: "refresh" | "settings" | "update" | "output" | "mounted" } | { type: "search"; query: string } - | { type: "networkSearch"; enabled: boolean } + | { type: "networkSearch"; enabled: boolean; token?: string } | { type: "open"; id: string }; export type UiLabel = (key: string) => string; @@ -187,7 +189,7 @@ export function badgeLabels(badges: readonly BadgeKey[], label: UiLabel): string } function renderRow(row: LibraryRow, label: UiLabel): string { - const badges = badgeLabels(row.badges, label); + const badges: string[] = []; const openTitle = fill(label, LIBRARY_UI.open, [row.id]); const surface = row.surface === undefined ? undefined : surfaceLabel(row.surface, label); const version = @@ -197,14 +199,14 @@ function renderRow(row: LibraryRow, label: UiLabel): string { ...badges.map((badge) => `${escapeHtml(badge)}`), row.added ? `${escapeHtml(label(LIBRARY_UI.added))}` : "", row.unreadable ? `${escapeHtml(label(LIBRARY_UI.unreadable))}` : "", - row.crossRegistry === true ? `${escapeHtml(label(LIBRARY_UI.crossRegistry))}` : "", + row.crossRegistry === true || row.source ? `${escapeHtml(row.source ?? label(LIBRARY_UI.crossRegistry))}` : "", ] .filter((part) => part.length > 0) .join(""); const description = row.description === undefined ? "" : row.description; return [ `

`, - ` `, ` `, ` `, ` ${escapeHtml(label(LIBRARY_UI.networkSearch))}`, ` `, + ` ${escapeHtml(fill(label, LIBRARY_UI.count, [model.rows.filter((row) => !row.crossRegistry && rowMatchesClient(model, row)).length, model.rows.filter((row) => !row.crossRegistry).length]))}`, ``, ].join("\n"); } function renderList(model: LibraryModel, label: UiLabel): string { - if (model.rows.length === 0) { - return `

${escapeHtml(model.notice ?? label(LIBRARY_UI.noResults))}

`; - } - return [ - `

`, - model.rows.map((row) => renderRow(row, label)).join("\n"), - ``, - ``, - ].join("\n"); + const local = model.rows.filter((row) => !row.crossRegistry); + const extra = model.rows.filter((row) => row.crossRegistry); + return `

+ ${model.projectNotice ? `

${escapeHtml(model.projectNotice)}

` : ""} +

${local.map((row) => renderRow(row, label)).join("\n")} +

${escapeHtml(label(LIBRARY_UI.other))} (${extra.length})

${extra.map((row) => renderRow(row, label)).join("\n")} +

${escapeHtml(model.notice ?? label(LIBRARY_UI.noResults))}

${escapeHtml(model.status ?? "")}

`; } /** @@ -272,72 +279,98 @@ function clientScript(initialModel: string): string { "use strict"; var api = typeof acquireVsCodeApi === "function" ? acquireVsCodeApi() : undefined; var state = ${initialModel}; + var saved = api && api.getState ? api.getState() || {} : {}; var searchInput = document.getElementById("library-search"); var networkInput = document.getElementById("library-network"); - var list = document.getElementById("library-list"); - var empty = document.getElementById("library-empty"); - var countElement = document.getElementById("library-count"); - - function post(message) { - if (api) { api.postMessage(message); } + var networkToken; + var networkSequence = 0; + var selected = state.selectedKey || saved.selected || ""; + if (searchInput && typeof saved.query === "string") { searchInput.value = saved.query; } + function post(message) { if (api) { api.postMessage(message); } } + function persist() { + if (api && api.setState) { api.setState({ query: searchInput.value, selected: selected, scroll: window.scrollY }); } } - - // Every whitespace-separated word has to appear in the row's haystack, which - // the host builds from the id, the name, the description and the usage labels. - function rowMatches(row, query) { - if (query.length === 0) { return true; } - var haystack = row.getAttribute("data-haystack") || ""; - var parts = query.split(/\\s+/); - for (var index = 0; index < parts.length; index += 1) { - if (parts[index].length > 0 && haystack.indexOf(parts[index]) < 0) { return false; } - } - return true; - } - function apply() { - var query = searchInput ? searchInput.value.trim().toLowerCase() : ""; - var any = false; - var visible = 0; + document.querySelector('[data-action="clear"]').hidden = searchInput.value.length === 0; + var query = searchInput.value.trim().toLowerCase(); + var parts = query.split(/\\s+/); + var rows = Array.from(document.querySelectorAll("[data-row]")); + var local = 0; + var extra = 0; + rows.forEach(function (row) { + var haystack = row.getAttribute("data-haystack") || ""; + var shown = parts.every(function (part) { return !part || haystack.indexOf(part) >= 0; }); + row.parentNode.hidden = !shown; + if (shown) { if (row.getAttribute("data-cross") === "true") { extra++; } else { local++; } } + if (row.getAttribute("data-row") === selected) { row.setAttribute("aria-current", "true"); } + else { row.removeAttribute("aria-current"); } + }); + var list = document.getElementById("library-list"); if (list) { - var rows = list.querySelectorAll("[data-row]"); - for (var index = 0; index < rows.length; index += 1) { - var shown = rowMatches(rows[index], query); - rows[index].parentNode.hidden = !shown; - if (shown) { any = true; visible += 1; } - } - list.hidden = !any; - } - if (empty) { empty.hidden = any || !list; } - if (countElement) { - var template = state && state.countTemplate ? state.countTemplate : ""; - var total = state && state.total ? state.total : 0; - countElement.textContent = template.split("{0}").join(String(visible)).split("{1}").join(String(total)); + Array.from(list.children).sort(function (a, b) { + function rank(item) { + var id = item.firstElementChild.getAttribute("data-id").toLowerCase(); + var name = id.slice(id.lastIndexOf(".") + 1); + return !query ? 2 : id === query || name === query ? 0 : id.indexOf(query) === 0 || name.indexOf(query) === 0 ? 1 : 2; + } + return rank(a) - rank(b) || a.firstElementChild.getAttribute("data-id").localeCompare(b.firstElementChild.getAttribute("data-id")); + }).forEach(function (item) { list.appendChild(item); }); } + var empty = document.getElementById("library-empty"); + if (empty) { empty.hidden = local + extra > 0; } + var group = document.getElementById("library-extra"); + if (group) { group.hidden = extra === 0; } + document.getElementById("library-count").textContent = state.countTemplate.split("{0}").join(String(local)).split("{1}").join(String(state.localTotal)); + persist(); } - - if (searchInput) { - searchInput.addEventListener("input", function () { - apply(); - post({ type: "search", query: searchInput.value }); - }); - } - if (networkInput) { - networkInput.addEventListener("change", function () { - post({ type: "networkSearch", enabled: networkInput.checked === true }); - }); - } + searchInput.addEventListener("input", function () { apply(); post({ type: "search", query: searchInput.value }); }); + networkInput.addEventListener("change", function () { networkToken = Date.now() + "-" + (++networkSequence); post({ type: "networkSearch", enabled: networkInput.checked, token: networkToken }); }); document.addEventListener("click", function (event) { - var target = event.target; - if (!target || typeof target.closest !== "function") { return; } - var refresh = target.closest("[data-action]"); - if (refresh && refresh.getAttribute("data-action") === "refresh") { - post({ type: "refresh" }); - return; + var target = event.target.closest && event.target.closest("[data-action], [data-row]"); + if (!target) { return; } + var action = target.getAttribute("data-action"); + if (action === "clear") { searchInput.value = ""; searchInput.focus(); apply(); post({ type: "search", query: "" }); return; } + if (action) { post({ type: action }); return; } + selected = target.getAttribute("data-row"); apply(); post({ type: "open", id: selected }); + }); + document.addEventListener("keydown", function (event) { + if (event.key === "Escape" && event.target === searchInput) { + searchInput.value = ""; apply(); post({ type: "search", query: "" }); } - var row = target.closest("[data-row]"); - if (row) { post({ type: "open", id: row.getAttribute("data-row") }); } + if (event.key !== "ArrowDown" && event.key !== "ArrowUp") { return; } + var rows = Array.from(document.querySelectorAll("[data-row]")).filter(function (row) { return !row.parentNode.hidden; }); + if (!rows.length || (event.target !== searchInput && !event.target.hasAttribute("data-row"))) { return; } + event.preventDefault(); + var index = rows.indexOf(document.activeElement); + var next = event.key === "ArrowDown" ? Math.min(rows.length - 1, index + 1) : Math.max(0, index - 1); + rows[next].focus(); + }); + window.addEventListener("scroll", persist); + window.addEventListener("message", function (event) { + var payload = event.data; + if (payload && payload.type === "networkSearchSaved") { if (payload.token === networkToken) { networkToken = undefined; networkInput.checked = payload.enabled; } return; } + if (!payload || payload.type !== "libraryUpdate") { return; } + var scroll = window.scrollY; + var focused = document.activeElement && document.activeElement.getAttribute("data-row"); + var details = document.querySelector("footer details"); + var expanded = details && details.open; + var doc = new DOMParser().parseFromString(payload.html, "text/html"); + ["library-results", "library-footer"].forEach(function (id) { + var old = document.getElementById(id); var next = doc.getElementById(id); + if (old && next) { old.replaceWith(next); } + }); + state = payload.state; + if (state.selectedKey) { selected = state.selectedKey; } + if (!networkToken) { networkInput.checked = payload.networkSearch; } + apply(); + var nextDetails = document.querySelector("footer details"); if (nextDetails) { nextDetails.open = expanded; } + if (focused) { Array.from(document.querySelectorAll("[data-row]")).some(function (row) { if (row.getAttribute("data-row") === focused) { row.focus(); return true; } return false; }); } + window.scrollTo(0, scroll); }); apply(); + window.scrollTo(0, saved.scroll || 0); + post({ type: "mounted" }); + post({ type: "search", query: searchInput.value }); })();`; } @@ -348,10 +381,12 @@ function clientScript(initialModel: string): string { * embedding the model again would double the page for nothing. `<` is escaped in * `embedJson`, so even this cannot close the script element. */ -function clientState(model: LibraryModel): Record { +export function libraryClientState(model: LibraryModel): Record { return { countTemplate: model.countTemplate, + selectedKey: model.selectedKey, total: model.total, + localTotal: model.rows.filter((row) => !row.crossRegistry).length, query: model.query, }; } @@ -380,20 +415,24 @@ export function renderLibraryHtml(model: LibraryModel, assets: LibraryAssets): s ${escapeHtml(label(LIBRARY_UI.title))} -

+ ${renderToolbar(model, label)}

${renderList(model, label)}

${escapeHtml(label(CACHE_PANEL_UI.sharedTitle))}

`, + ` `, + `

${escapeHtml(label(PANEL_UI.title))}

${escapeHtml(model.id)}

${escapeHtml(versionsHeading)}

${escapeHtml(label(DETAIL_UI.dependencies))}

${escapeHtml(label(DETAIL_UI.code))}

${escapeHtml(label(DETAIL_UI.overview))}

${escapeHtml(label(LIBRARY_UI.title))}

${escapeHtml(index === 0 ? label(DETAIL_UI.code) : snippet.file.split("/").pop() ?? snippet.file)}

${escapeHtml(model.id)}

${escapeHtml(model.id)}

${escapeHtml(versionsHeading)}

${escapeHtml(label(DETAIL_UI.dependencies))}

${escapeHtml(label(DETAIL_UI.code))}

${escapeHtml(label(DETAIL_UI.overview))}

${escapeHtml(label(DETAIL_UI.usage))}

${escapeHtml(label(LIBRARY_UI.other))} (${extra.length})

${escapeHtml(label(CACHE_PANEL_UI.sharedTitle))}

${escapeHtml(label(CACHE_PANEL_UI.title))}

`, + ` `, + ` ${escapeHtml(section.title)}`, + ` `, + `

${escapeHtml(versionsHeading)}

${escapeHtml(label(DETAIL_UI.dependencies))}

${escapeHtml(label(DETAIL_UI.code))}

${escapeHtml(label(DETAIL_UI.overview))}

${escapeHtml(index === 0 ? label(DETAIL_UI.code) : snippet.file.split("/").pop() ?? snippet.file)}

${escapeHtml(label(LIBRARY_UI.other))} (${extra.length})

`, + ` `, + `