topchester-ai 0.27.0 → 0.29.0

package/dist/cli.d.mts

@@ -1 +1,7 @@
-export { };
+//#region src/cli.d.ts
+declare function runTopchesterCli(argv?: string[], options?: {
+  exitOverride?: boolean;
+}): Promise<void>;
+//#endregion
+export { runTopchesterCli };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.mjs

@@ -2,6 +2,7 @@
 import { createRequire } from "node:module";
 import { cwd, stderr, stdout } from "node:process";
 import { basename, delimiter, dirname, extname, isAbsolute, join, parse, relative, resolve, sep, win32 } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { generateText, streamText, tool } from "ai";
@@ -11,12 +12,12 @@ import { execFile, spawn } from "node:child_process";
 import { constants, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { parse as parse$1, parseDocument } from "yaml";
-import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import pino from "pino";
 import picomatch from "picomatch";
 import { uuidv7 } from "uuidv7";
 import { CURSOR_MARKER, Markdown, ProcessTerminal, TUI, decodeKittyPrintable, isKeyRelease, isKeyRepeat, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { diffWords } from "diff";
 import { highlight, supportsLanguage } from "cli-highlight";
 //#region src/agent/tools/ai-sdk-tools.ts
 function toAiSdkToolSet(definitions) {
@@ -3088,6 +3089,10 @@ const ui = {
 	error(text) {
 		return color(text, "red");
 	},
+	inverse(text) {
+		if (!shouldUseColor()) return text;
+		return `\u001b[7m${text}\u001b[27m`;
+	},
 	softBackground(text) {
 		return color(text, "bgSoftGray");
 	},
@@ -7556,6 +7561,85 @@ const queryStopWords = new Set([
 	"when"
 ]);
 //#endregion
+//#region src/tui/diff.ts
+function renderUnifiedDiff(diffText, options = {}) {
+	const indent = options.indent ?? "";
+	const wrapWidth = options.width === void 0 ? void 0 : Math.max(1, options.width - indent.length);
+	const rawLines = diffText.split("\n");
+	const rendered = [];
+	let index = 0;
+	while (index < rawLines.length) {
+		const line = rawLines[index];
+		if (isRemovedBodyLine(line)) {
+			const removed = [];
+			while (index < rawLines.length && isRemovedBodyLine(rawLines[index])) {
+				removed.push({
+					kind: "removed",
+					content: rawLines[index].slice(1)
+				});
+				index += 1;
+			}
+			const added = [];
+			while (index < rawLines.length && isAddedBodyLine(rawLines[index])) {
+				added.push({
+					kind: "added",
+					content: rawLines[index].slice(1)
+				});
+				index += 1;
+			}
+			rendered.push(...renderChangedLines(removed, added, indent, wrapWidth));
+			continue;
+		}
+		if (isAddedBodyLine(line)) rendered.push(...renderWrappedLine(ui.ok(`+${expandTabs$1(line.slice(1))}`), indent, wrapWidth));
+		else if (line.startsWith("@@")) rendered.push(...renderWrappedLine(ui.model(line), indent, wrapWidth));
+		else if (line.startsWith("diff --git ") || line.startsWith("--- ") || line.startsWith("+++ ")) rendered.push(...renderWrappedLine(ui.muted(line), indent, wrapWidth));
+		else if (line.startsWith(" ")) rendered.push(...renderWrappedLine(ui.label(` ${expandTabs$1(line.slice(1))}`), indent, wrapWidth));
+		else if (line.length > 0) rendered.push(...renderWrappedLine(ui.label(line), indent, wrapWidth));
+		index += 1;
+	}
+	return rendered;
+}
+function renderChangedLines(removedLines, addedLines, indent, wrapWidth) {
+	if (removedLines.length === 1 && addedLines.length === 1) {
+		const { removed, added } = renderIntraLineDiff(expandTabs$1(removedLines[0].content), expandTabs$1(addedLines[0].content));
+		return [...renderWrappedLine(ui.error(`-${removed}`), indent, wrapWidth), ...renderWrappedLine(ui.ok(`+${added}`), indent, wrapWidth)];
+	}
+	return [...removedLines.flatMap((line) => renderWrappedLine(ui.error(`-${expandTabs$1(line.content)}`), indent, wrapWidth)), ...addedLines.flatMap((line) => renderWrappedLine(ui.ok(`+${expandTabs$1(line.content)}`), indent, wrapWidth))];
+}
+function renderIntraLineDiff(oldContent, newContent) {
+	const parts = diffWords(oldContent, newContent);
+	let removed = "";
+	let added = "";
+	for (const part of parts) if (part.removed) removed += highlightChangedPart(part.value);
+	else if (part.added) added += highlightChangedPart(part.value);
+	else {
+		removed += part.value;
+		added += part.value;
+	}
+	return {
+		removed,
+		added
+	};
+}
+function highlightChangedPart(value) {
+	const leading = value.match(/^\s*/u)?.[0] ?? "";
+	const trailing = value.match(/\s*$/u)?.[0] ?? "";
+	const body = value.slice(leading.length, value.length - trailing.length);
+	return body.length === 0 ? value : `${leading}${ui.inverse(body)}${trailing}`;
+}
+function renderWrappedLine(line, indent, width) {
+	return (width === void 0 ? [line] : wrapTextWithAnsi(line, width)).map((part) => `${indent}${part}`);
+}
+function isRemovedBodyLine(line) {
+	return line.startsWith("-") && !line.startsWith("--- ");
+}
+function isAddedBodyLine(line) {
+	return line.startsWith("+") && !line.startsWith("+++ ");
+}
+function expandTabs$1(text) {
+	return text.replace(/\t/gu, "    ");
+}
+//#endregion
 //#region src/tui/markdown.ts
 const codeFenceSentinel = "topchester-code-fence";
 function renderMarkdown(text, width) {
@@ -7647,16 +7731,13 @@ function thinkingMessage(text) {
 		text
 	};
 }
-function toolCallMessage(call, label, resultSummary) {
-	return resultSummary === void 0 ? {
-		kind: "tool_call",
-		call,
-		label
-	} : {
+function toolCallMessage(call, label, resultSummary, diff) {
+	return {
 		kind: "tool_call",
 		call,
 		label,
-		resultSummary
+		...resultSummary === void 0 ? {} : { resultSummary },
+		...diff === void 0 ? {} : { diff }
 	};
 }
 function hookStatusMessage(label, eventName, statusMessage) {
@@ -7682,7 +7763,7 @@ function modalMessage(message) {
 const DEFAULT_MODAL_VISIBLE_ACTION_LIMIT = 16;
 function renderChatMessage(message, options = {}) {
 	if (message.kind === "modal") return renderChatModal(message, options.selectedActionIndex, options.maxModalHeight, options.width);
-	if (message.kind === "tool_call") return renderToolCallMessage(message);
+	if (message.kind === "tool_call") return renderToolCallMessage(message, options.width);
 	if (message.kind === "hook_status") return renderHookStatusMessage(message);
 	if (message.kind === "subagent") return renderSubagentMessage(message);
 	if (message.kind === "thinking") return message.text.split("\n").map((line) => ui.muted(line));
@@ -7714,9 +7795,14 @@ function renderSystemMessage(lines) {
 function formatSystemBodyLine(line) {
 	return expandTabs(line).replace(/\(changed \+\d+\/-\d+\)$/u, (summary) => ui.muted(summary)).replace(/\(created \+\d+\)$/u, (summary) => ui.muted(summary));
 }
-function renderToolCallMessage(message) {
+function renderToolCallMessage(message, width) {
 	const visibleLabel = message.resultSummary && !message.label.includes(message.resultSummary) ? `${message.label} ${message.resultSummary}` : message.label;
-	return [`   ${ui.muted(expandTabs(visibleLabel))}`];
+	const label = `   ${ui.muted(expandTabs(visibleLabel))}`;
+	if (!message.diff) return [label];
+	return [label, ...renderUnifiedDiff(message.diff, {
+		indent: "     ",
+		width
+	})];
 }
 function renderHookStatusMessage(message) {
 	return [` ${ui.muted(expandTabs(message.label))}`];
@@ -7888,7 +7974,8 @@ const messagePayloadSchema = z.object({
 const toolCallPayloadSchema = z.object({
 	kind: z.literal("tool_call"),
 	label: z.string(),
-	call: z.record(z.string(), jsonValueSchema)
+	call: z.record(z.string(), jsonValueSchema),
+	diff: z.string().optional()
 });
 const hookStatusPayloadSchema = z.object({
 	kind: z.literal("hook_status"),
@@ -8133,7 +8220,7 @@ function rehydrateSession(events) {
 			if (event.role === "user") visibleOnlyActionValues = /* @__PURE__ */ new Set();
 			break;
 		case "tool_call":
-			messages.push(toolCallMessage(event.call, event.label));
+			messages.push(toolCallMessage(event.call, event.label, void 0, event.diff));
 			break;
 		case "hook_status":
 			messages.push(hookStatusMessage(event.label, event.eventName, event.statusMessage));
@@ -8757,11 +8844,16 @@ const agentEvent = {
 			meta
 		};
 	},
-	toolCall(call, label) {
-		return {
+	toolCall(call, label, diff) {
+		return diff === void 0 ? {
 			type: "tool_call",
 			call,
 			label
+		} : {
+			type: "tool_call",
+			call,
+			label,
+			diff
 		};
 	},
 	hookStatus(eventName, statusMessage) {
@@ -10487,7 +10579,8 @@ function runtimeEventToSessionPayload(event) {
 		case "tool_call": return {
 			kind: "tool_call",
 			label: event.label,
-			call: event.call
+			call: event.call,
+			...event.diff === void 0 ? {} : { diff: event.diff }
 		};
 		case "hook_status": return {
 			kind: "hook_status",
@@ -11380,7 +11473,7 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 					const call = taskCalls[index];
 					const toolResult = taskResults[index];
 					for (const event of createInstructionContextEventsFromToolResult(toolResult, persistedProjectInstructionKeys)) yield event;
-					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult));
+					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult), getToolCallDisplayDiff(toolResult));
 					const postHookRun = this.startPostToolUseHook(call, modelToolCalls[index]?.id, toolResult, session, abortSignal);
 					for await (const event of postHookRun.statusEvents) yield event;
 					const postHook = await postHookRun.result;
@@ -11442,7 +11535,7 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 					const call = parallelCalls[index];
 					const toolResult = parallelResults[index];
 					for (const event of createInstructionContextEventsFromToolResult(toolResult, persistedProjectInstructionKeys)) yield event;
-					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult));
+					yield agentEvent.toolCall(call, formatToolCallMessage(call, toolResult), getToolCallDisplayDiff(toolResult));
 					const postHookRun = this.startPostToolUseHook(call, modelToolCalls[index]?.id, toolResult, session, abortSignal);
 					for await (const event of postHookRun.statusEvents) yield event;
 					const postHook = await postHookRun.result;
@@ -11505,7 +11598,7 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 				}
 			}
 			for (const event of createInstructionContextEventsFromToolResult(toolResult, persistedProjectInstructionKeys)) yield event;
-			yield agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult));
+			yield agentEvent.toolCall(executableToolCall, formatToolCallMessage(executableToolCall, toolResult), getToolCallDisplayDiff(toolResult));
 			if (!isToolErrorResult(toolResult) && toolResult.tool === "plan_todo") yield agentEvent.taskPlan(toolResult.plan);
 			const postHookRun = this.startPostToolUseHook(executableToolCall, toolCall.id, toolResult, session, abortSignal);
 			for await (const event of postHookRun.statusEvents) yield event;
@@ -11811,6 +11904,9 @@ function createToolErrorResult(tool, message) {
 		warning: message
 	};
 }
+function getToolCallDisplayDiff(result) {
+	if (result.tool === "edit_file" && !isToolErrorResult(result) && "diff" in result) return result.diff;
+}
 function isL1ContextDisabledByEnv() {
 	const value = process.env.TOPCHESTER_DISABLE_L1_CONTEXT?.trim().toLowerCase();
 	return value === "1" || value === "true" || value === "yes" || value === "on";
@@ -11851,7 +11947,7 @@ function createInstructionContextEvents(sources, persistedKeys) {
 function renderRuntimeEvent(event) {
 	switch (event.type) {
 		case "message": return [event.role === "assistant" ? agentMessage(event.text, event.meta) : systemMessage(event.text)];
-		case "tool_call": return [toolCallMessage(event.call, event.label)];
+		case "tool_call": return [toolCallMessage(event.call, event.label, void 0, event.diff)];
 		case "hook_status": return [hookStatusMessage(event.label, event.eventName, event.statusMessage)];
 		case "knowledge_status": return [systemMessage([`KB status: ${formatKnowledgePathStatus(event.status)}${formatKbPathSource(event.status)}`, event.guidance].filter(Boolean).join("\n"))];
 		case "choice": return [modalMessage({
@@ -12111,7 +12207,8 @@ function chatMessageToSessionPayload(message) {
 	if (message.kind === "tool_call") return {
 		kind: "tool_call",
 		label: message.label,
-		call: message.call
+		call: message.call,
+		...message.diff === void 0 ? {} : { diff: message.diff }
 	};
 }
 function slashCommandToSessionPayload(command) {
@@ -13316,104 +13413,112 @@ function defaultSelfUpdateRunner(command, args) {
 }
 //#endregion
 //#region src/cli.ts
-const program = new Command();
-program.name("topchester").description("KB-first terminal coding agent").version(getTopchesterVersion());
-program.option("-c, --config <path>", "explicit config file path").option("--workspace <path>", "workspace root", cwd()).option("--resume <session>", "resume a project session: latest or an exact session id").option("--dev <flag>", "enable a development flag", collectDevFlag, []);
-program.action(async () => {
-	const context = createContextFromOptions();
-	const options = program.opts();
-	try {
-		if (options.resume) {
-			const loaded = await loadSession(context.workspaceRoot, options.resume);
-			const session = await loadSessionForAppend(context.workspaceRoot, loaded.sessionId);
-			const rehydrated = rehydrateSession(loaded.events);
-			await new TopchesterTuiShell(context, void 0, {
-				session,
-				initialMessages: rehydrated.messages,
-				initialTaskPlan: rehydrated.taskPlan
-			}).render();
-			return;
+async function runTopchesterCli(argv = process.argv, options = {}) {
+	const program = createTopchesterProgram();
+	if (options.exitOverride) program.exitOverride();
+	await program.parseAsync(argv);
+}
+function createTopchesterProgram() {
+	const program = new Command();
+	program.name("topchester").description("KB-first terminal coding agent").version(getTopchesterVersion());
+	program.option("-c, --config <path>", "explicit config file path").option("--workspace <path>", "workspace root", cwd()).option("--resume <session>", "resume a project session: latest or an exact session id").option("--dev <flag>", "enable a development flag", collectDevFlag, []);
+	program.action(async () => {
+		const context = createContextFromOptions(program);
+		const options = program.opts();
+		try {
+			if (options.resume) {
+				const loaded = await loadSession(context.workspaceRoot, options.resume);
+				const session = await loadSessionForAppend(context.workspaceRoot, loaded.sessionId);
+				const rehydrated = rehydrateSession(loaded.events);
+				await new TopchesterTuiShell(context, void 0, {
+					session,
+					initialMessages: rehydrated.messages,
+					initialTaskPlan: rehydrated.taskPlan
+				}).render();
+				return;
+			}
+			await new TopchesterTuiShell(context).render();
+		} catch (error) {
+			console.error(formatStartupError(error));
+			process.exitCode = 1;
 		}
-		await new TopchesterTuiShell(context).render();
-	} catch (error) {
-		console.error(formatStartupError(error));
-		process.exitCode = 1;
-	}
-});
-program.command("dev").description("start local development mode").action(() => {
-	const context = createContextFromOptions();
-	console.log("Topchester local dev mode");
-	printStartupSummary(context);
-});
-program.command("run").description("run one prompt or slash command without opening the TUI").argument("<prompt...>", "prompt text or slash command").option("--model <model>", "override the agent.primary model for this run").option("--timeout <ms>", "timeout for the run in milliseconds", parsePositiveInteger).option("--json", "write JSONL run events to stdout").option("--output-json <path>", "write JSONL run events to a file").action(async (promptParts, options) => {
-	const context = createContextFromOptions();
-	const globalOptions = program.opts();
-	try {
-		await executeRunCommand(context, {
-			prompt: promptParts.join(" "),
-			model: options.model,
-			timeoutMs: options.timeout,
-			json: options.json,
-			outputJson: options.outputJson,
-			resume: globalOptions.resume
-		});
-	} catch (error) {
-		console.error(formatStartupError(error));
-		process.exitCode = 1;
-	}
-});
-program.command("search").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
-	await executeKbSearchCommand(queryParts, options);
-});
-const kbCommand = program.command("kb").description("knowledge base commands");
-kbCommand.command("init").description("initialize a project knowledge base").action(async () => {
-	const context = createContextFromOptions();
-	const result = await ui.progress("Preparing project knowledge folders...", (report) => initializeKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
-	console.log(formatKnowledgeInitResult(result).join("\n"));
-});
-kbCommand.command("dry-run").description("list project files that would be synced into the knowledge base").action(async () => {
-	const context = createContextFromOptions();
-	const result = await ui.spinner("Listing project files for KB sync...", () => dryRunKnowledgeCompile(context.workspaceRoot, { config: context.config }));
-	console.log(formatKnowledgeCompileDryRunResult(result, { formatSyncStatus: formatDryRunSyncStatus }).join("\n"));
-});
-kbCommand.command("sync").description("sync project files into the knowledge base").option("--full", "sync all in-scope files and remove orphaned L1 entries").action(async (options) => {
-	const context = createContextFromOptions();
-	const result = await ui.progress(options.full ? "Syncing all L1 file entries..." : "Syncing non-clean L1 file entries...", (report) => syncKnowledgeBase(context.workspaceRoot, {
-		model: context.modelGateway,
-		requireModel: true,
-		config: context.config,
-		full: options.full,
-		onProgress: (event) => report(event.message)
-	}));
-	console.log(formatKnowledgeSyncResult(result, { title: options.full ? "KB sync --full" : "KB sync" }).join("\n"));
-	if (isPartialKnowledgeCompileResult(result)) process.exitCode = 2;
-});
-kbCommand.command("search").alias("query").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
-	await executeKbSearchCommand(queryParts, options);
-});
-kbCommand.command("context").description("create an L1 context pack for a query").argument("<query...>", "context query").option("--limit <count>", "maximum number of relevant files", parsePositiveInteger).option("--min-score <score>", "minimum match score", parseNonNegativeNumber).option("--json", "write JSON context pack to stdout").option("--full-l1", "include full raw L1 entries in JSON output").action(async (queryParts, options) => {
-	await executeKbContextCommand(queryParts, options);
-});
-kbCommand.command("reset").description("delete the local project knowledge base and cache").action(async () => {
-	const context = createContextFromOptions();
-	const result = await ui.progress("Resetting project knowledge base...", (report) => resetKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
-	console.log(formatKnowledgeResetResult(result).join("\n"));
-});
-kbCommand.command("status").description("show project files that are not current in the knowledge base").action(async () => {
-	const context = createContextFromOptions();
-	const result = await ui.spinner("Checking KB file status...", async () => filterNonCleanKnowledgeCompileResult(await dryRunKnowledgeCompile(context.workspaceRoot, { config: context.config })));
-	console.log(formatKnowledgeCompileStatusResult(result, { formatSyncStatus: formatDryRunSyncStatus }).join("\n"));
-});
-program.command("update").alias("upgrade").description("update Topchester with the package manager that installed it").argument("[target]", "version or npm dist tag to install", "latest").action(async (target) => {
-	try {
-		const command = await runSelfUpdate({ target });
-		console.log(formatSelfUpdateSuccess(command).join("\n"));
-	} catch (error) {
-		console.error(formatStartupError(error));
-		process.exitCode = 1;
-	}
-});
-await program.parseAsync();
+	});
+	program.command("dev").description("start local development mode").action(() => {
+		const context = createContextFromOptions(program);
+		console.log("Topchester local dev mode");
+		printStartupSummary(context);
+	});
+	program.command("run").description("run one prompt or slash command without opening the TUI").argument("<prompt...>", "prompt text or slash command").option("--model <model>", "override the agent.primary model for this run").option("--timeout <ms>", "timeout for the run in milliseconds", parsePositiveInteger).option("--json", "write JSONL run events to stdout").option("--output-json <path>", "write JSONL run events to a file").action(async (promptParts, options) => {
+		const context = createContextFromOptions(program);
+		const globalOptions = program.opts();
+		try {
+			await executeRunCommand(context, {
+				prompt: promptParts.join(" "),
+				model: options.model,
+				timeoutMs: options.timeout,
+				json: options.json,
+				outputJson: options.outputJson,
+				resume: globalOptions.resume
+			});
+		} catch (error) {
+			console.error(formatStartupError(error));
+			process.exitCode = 1;
+		}
+	});
+	program.command("search").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+		await executeKbSearchCommand(program, queryParts, options);
+	});
+	const kbCommand = program.command("kb").description("knowledge base commands");
+	kbCommand.command("init").description("initialize a project knowledge base").action(async () => {
+		const context = createContextFromOptions(program);
+		const result = await ui.progress("Preparing project knowledge folders...", (report) => initializeKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
+		console.log(formatKnowledgeInitResult(result).join("\n"));
+	});
+	kbCommand.command("dry-run").description("list project files that would be synced into the knowledge base").action(async () => {
+		const context = createContextFromOptions(program);
+		const result = await ui.spinner("Listing project files for KB sync...", () => dryRunKnowledgeCompile(context.workspaceRoot, { config: context.config }));
+		console.log(formatKnowledgeCompileDryRunResult(result, { formatSyncStatus: formatDryRunSyncStatus }).join("\n"));
+	});
+	kbCommand.command("sync").description("sync project files into the knowledge base").option("--full", "sync all in-scope files and remove orphaned L1 entries").action(async (options) => {
+		const context = createContextFromOptions(program);
+		const result = await ui.progress(options.full ? "Syncing all L1 file entries..." : "Syncing non-clean L1 file entries...", (report) => syncKnowledgeBase(context.workspaceRoot, {
+			model: context.modelGateway,
+			requireModel: true,
+			config: context.config,
+			full: options.full,
+			onProgress: (event) => report(event.message)
+		}));
+		console.log(formatKnowledgeSyncResult(result, { title: options.full ? "KB sync --full" : "KB sync" }).join("\n"));
+		if (isPartialKnowledgeCompileResult(result)) process.exitCode = 2;
+	});
+	kbCommand.command("search").alias("query").description("search compiled L1 knowledge entries").argument("<query...>", "search query").option("--limit <count>", "maximum number of matches", parsePositiveInteger).option("--json", "write full JSON search result to stdout").action(async (queryParts, options) => {
+		await executeKbSearchCommand(program, queryParts, options);
+	});
+	kbCommand.command("context").description("create an L1 context pack for a query").argument("<query...>", "context query").option("--limit <count>", "maximum number of relevant files", parsePositiveInteger).option("--min-score <score>", "minimum match score", parseNonNegativeNumber).option("--json", "write JSON context pack to stdout").option("--full-l1", "include full raw L1 entries in JSON output").action(async (queryParts, options) => {
+		await executeKbContextCommand(program, queryParts, options);
+	});
+	kbCommand.command("reset").description("delete the local project knowledge base and cache").action(async () => {
+		const context = createContextFromOptions(program);
+		const result = await ui.progress("Resetting project knowledge base...", (report) => resetKnowledgeBase(context.workspaceRoot, { onProgress: (event) => report(event.message) }));
+		console.log(formatKnowledgeResetResult(result).join("\n"));
+	});
+	kbCommand.command("status").description("show project files that are not current in the knowledge base").action(async () => {
+		const context = createContextFromOptions(program);
+		const result = await ui.spinner("Checking KB file status...", async () => filterNonCleanKnowledgeCompileResult(await dryRunKnowledgeCompile(context.workspaceRoot, { config: context.config })));
+		console.log(formatKnowledgeCompileStatusResult(result, { formatSyncStatus: formatDryRunSyncStatus }).join("\n"));
+	});
+	program.command("update").alias("upgrade").description("update Topchester with the package manager that installed it").argument("[target]", "version or npm dist tag to install", "latest").action(async (target) => {
+		try {
+			const command = await runSelfUpdate({ target });
+			console.log(formatSelfUpdateSuccess(command).join("\n"));
+		} catch (error) {
+			console.error(formatStartupError(error));
+			process.exitCode = 1;
+		}
+	});
+	return program;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await runTopchesterCli();
 function printStartupSummary(context) {
 	const assignments = context.config.models?.assignments ?? {};
 	const providers = context.config.models?.providers ?? {};
@@ -13441,7 +13546,7 @@ function printStartupSummary(context) {
 		}
 	}
 }
-function createContextFromOptions() {
+function createContextFromOptions(program) {
 	const options = program.opts();
 	return createAppContext({
 		workspaceRoot: options.workspace,
@@ -13449,8 +13554,8 @@ function createContextFromOptions() {
 		devFlags: options.dev
 	});
 }
-async function executeKbSearchCommand(queryParts, options) {
-	const context = createContextFromOptions();
+async function executeKbSearchCommand(program, queryParts, options) {
+	const context = createContextFromOptions(program);
 	const query = queryParts.join(" ");
 	const result = options.json ? await searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }) : await ui.spinner("Searching L1 knowledge entries...", () => searchL1Knowledge(context.workspaceRoot, query, { limit: options.limit }));
 	if (options.json) {
@@ -13459,8 +13564,8 @@ async function executeKbSearchCommand(queryParts, options) {
 	}
 	console.log(formatL1KnowledgeSearchResult(result).join("\n"));
 }
-async function executeKbContextCommand(queryParts, options) {
-	const context = createContextFromOptions();
+async function executeKbContextCommand(program, queryParts, options) {
+	const context = createContextFromOptions(program);
 	const query = queryParts.join(" ");
 	const contextPackOptions = {
 		limit: options.limit,
@@ -13498,6 +13603,6 @@ function formatDryRunSyncStatus(status) {
 	return ui.warn(status);
 }
 //#endregion
-export {};
+export { runTopchesterCli };
 
 //# sourceMappingURL=cli.mjs.map