topchester-ai 0.43.0 → 0.45.0

package/README.md

@@ -117,16 +117,12 @@ Do not commit API keys. Put keys in environment variables, a user config file, o
 
 Topchester reads config in this order, with later entries overriding earlier ones:
 
-1. `~/.config/topchester/config.yaml`
+1. `topchester.jsonc`
 2. `~/.config/topchester/config.jsonc`
-3. `topchester.yaml`
-4. `topchester.jsonc`
-5. `.topchester/config.local.yaml`
-6. `.topchester/config.local.jsonc`
-7. `TOPCHESTER_CONFIG`
-8. `--config <path>`
+3. `TOPCHESTER_CONFIG`
+4. `--config <path>`
 
-Prefer `topchester.jsonc` for new project config. YAML paths are kept for compatibility.
+On first startup, Topchester creates `~/.config/topchester/config.jsonc` with a commented minimal example. Uncomment it to set your personal default model, or keep shared project policy in `topchester.jsonc`.
 
 ## How The Knowledge Base Works
 
@@ -166,11 +162,12 @@ The package name is `topchester-ai`; the installed command is `topchester`.
 ## Read More
 
 - [Onboarding](onboarding.md)
-- [CLI Commands](docs/cli.md)
-- [TUI Guide](docs/tui.md)
-- [Skills](docs/skills.md)
-- [Configuration](docs/config.md)
-- [Model Configuration](docs/MODEL_CONFIG.md)
-- [Knowledge System](docs/KNOWLEDGE.md)
-- [Architecture](docs/ARCHITECTURE.md)
-- [Sessions](docs/SESSIONS.md)
+- [Docs](docs/README.md)
+- [Quickstart](docs/getting-started/quickstart.md)
+- [CLI Commands](docs/reference/cli.md)
+- [TUI](docs/features/tui.md)
+- [Skills](docs/features/skills.md)
+- [Configuration](docs/configuration/config-files.md)
+- [Models and providers](docs/configuration/models-and-providers.md)
+- [Knowledge base](docs/features/knowledge-base.md)
+- [Sessions](docs/features/sessions.md)

package/dist/bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as runTopchesterCli } from "./cli-CVWQPq7z.mjs";
+import { t as runTopchesterCli } from "./cli-BgMj4Ifj.mjs";
 //#region src/bin.ts
 await runTopchesterCli();
 //#endregion

package/dist/{cli-CVWQPq7z.mjs → cli-BgMj4Ifj.mjs}

@@ -7,9 +7,9 @@ import { generateText, stepCountIs, streamText, tool } from "ai";
 import { ZodError, z } from "zod";
 import { access, mkdir, open, readFile, readdir, realpath, rename, rm, stat, truncate, writeFile } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
-import { constants, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
-import { parse as parse$1, parseDocument } from "yaml";
+import { parseDocument } from "yaml";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import pino from "pino";
@@ -34,7 +34,7 @@ const DEFAULT_MAX_OUTPUT_LINES = 1e3;
 async function runProcess(options) {
 	const startedAt = Date.now();
 	const pathEnv = options.pathEnv ?? process.env.PATH ?? "";
-	const executablePath = options.executable.includes("/") || isAbsolute(options.executable) ? await resolveExecutablePath(options.executable) : await findExecutable$2(options.executable, pathEnv);
+	const executablePath = options.executable.includes("/") || isAbsolute(options.executable) ? await resolveExecutablePath(options.executable) : await findExecutable$3(options.executable, pathEnv);
 	if (!executablePath) return {
 		stdout: "",
 		stderr: `${options.missingExecutableLabel ?? "command"} could not run because '${options.executable}' is not available on PATH.\n`,
@@ -47,7 +47,7 @@ async function runProcess(options) {
 	};
 	return runSpawnedProcess(executablePath, options, startedAt, pathEnv);
 }
-async function findExecutable$2(name, pathEnv) {
+async function findExecutable$3(name, pathEnv) {
 	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
 		const executablePath = join(pathEntry, name);
 		try {
@@ -1200,7 +1200,7 @@ async function collectWorkspaceFilesWithNode(workspaceRoot, startPath) {
 	return files;
 }
 async function createRipgrepCollector(pathEnv, relativeStartPath) {
-	const command = await findExecutable$1("rg", pathEnv);
+	const command = await findExecutable$2("rg", pathEnv);
 	if (!command) return;
 	return {
 		name: "rg",
@@ -1216,8 +1216,8 @@ async function createRipgrepCollector(pathEnv, relativeStartPath) {
 	};
 }
 async function createFdCollector(pathEnv, relativeStartPath) {
-	const fdCommand = await findExecutable$1("fd", pathEnv);
-	const fdfindCommand = fdCommand ? void 0 : await findExecutable$1("fdfind", pathEnv);
+	const fdCommand = await findExecutable$2("fd", pathEnv);
+	const fdfindCommand = fdCommand ? void 0 : await findExecutable$2("fdfind", pathEnv);
 	const command = fdCommand ?? fdfindCommand;
 	if (!command) return;
 	return {
@@ -1237,7 +1237,7 @@ async function createFdCollector(pathEnv, relativeStartPath) {
 	};
 }
 async function createFindCollector(pathEnv, relativeStartPath) {
-	const command = await findExecutable$1("find", pathEnv);
+	const command = await findExecutable$2("find", pathEnv);
 	if (!command) return;
 	return {
 		name: "find",
@@ -1332,7 +1332,7 @@ function resolveWorkspaceScopedPath$3(workspaceRoot, path) {
 		relativePath: relativePath || "."
 	};
 }
-async function findExecutable$1(name, pathEnv) {
+async function findExecutable$2(name, pathEnv) {
 	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
 		const executablePath = join(pathEntry, name);
 		try {
@@ -2188,14 +2188,14 @@ function resolveWorkspaceScopedPath$2(workspaceRoot, path) {
 }
 async function findSearchExecutable(pathEnv = process.env.PATH ?? "") {
 	for (const name of ["rg", "grep"]) {
-		const executablePath = await findExecutable(name, pathEnv);
+		const executablePath = await findExecutable$1(name, pathEnv);
 		if (executablePath) return {
 			name,
 			path: executablePath
 		};
 	}
 }
-async function findExecutable(name, pathEnv) {
+async function findExecutable$1(name, pathEnv) {
 	for (const pathEntry of pathEnv.split(delimiter).filter(Boolean)) {
 		const executablePath = join(pathEntry, name);
 		try {
@@ -5668,16 +5668,16 @@ function ensureGlobalTopchesterConfigDir() {
 	});
 	return dir;
 }
+function ensureGlobalTopchesterConfigFile() {
+	const configPath = getGlobalTopchesterConfigPath();
+	if (!existsSync(configPath)) {
+		ensureGlobalTopchesterConfigDir();
+		writeFileSync(configPath, getCommentedStarterConfig(), { mode: 384 });
+	}
+	return configPath;
+}
 function loadTopchesterConfig(options) {
-	const globalConfigDir = getGlobalTopchesterConfigDir();
-	const paths = [
-		join(options.workspaceRoot, "topchester.yaml"),
-		join(options.workspaceRoot, "topchester.jsonc"),
-		join(globalConfigDir, "config.yaml"),
-		join(globalConfigDir, "config.jsonc"),
-		process.env.TOPCHESTER_CONFIG,
-		options.configPath
-	].filter((path) => Boolean(path));
+	const paths = getTopchesterConfigSources(options).map((source) => source.path).filter((path) => Boolean(path));
 	let merged = {};
 	for (const path of paths) {
 		const resolvedPath = isAbsolute(path) ? path : resolve(options.workspaceRoot, path);
@@ -5687,6 +5687,33 @@ function loadTopchesterConfig(options) {
 	}
 	return topchesterConfigSchema.parse(merged);
 }
+function getTopchesterConfigSources(options) {
+	return [
+		{
+			label: "workspace",
+			path: join(options.workspaceRoot, "topchester.jsonc")
+		},
+		{
+			label: "user",
+			path: getGlobalTopchesterConfigPath()
+		},
+		{
+			label: "env",
+			path: process.env.TOPCHESTER_CONFIG || void 0
+		},
+		{
+			label: "cli",
+			path: options.configPath
+		}
+	].map((source) => {
+		const resolvedPath = source.path === void 0 ? void 0 : isAbsolute(source.path) ? source.path : resolve(options.workspaceRoot, source.path);
+		return {
+			label: source.label,
+			...resolvedPath === void 0 ? {} : { path: resolvedPath },
+			exists: resolvedPath === void 0 ? false : existsSync(resolvedPath)
+		};
+	});
+}
 const openRouterProviderDefaults = {
 	type: "openai-compatible",
 	baseURL: "https://openrouter.ai/api/v1",
@@ -5821,11 +5848,100 @@ function ensureStringArrayProperty(parent, key) {
 }
 function readConfigFile(path) {
 	try {
-		return parse$1(readFileSync(path, "utf8"));
+		return parseJsonc(readFileSync(path, "utf8"));
 	} catch (error) {
 		throw new Error(`Invalid Topchester config at ${path}: ${formatErrorMessage$1(error)}`);
 	}
 }
+function parseJsonc(source) {
+	const stripped = stripJsoncSyntax(source);
+	return stripped.trim() ? JSON.parse(stripped) : {};
+}
+function getCommentedStarterConfig() {
+	return [
+		"// Uncomment and edit this minimal config to choose a default model.",
+		"// {",
+		"//   \"models\": {",
+		"//     \"default\": \"openrouter/google/gemini-3.1-flash-lite\",",
+		"//   },",
+		"// }",
+		""
+	].join("\n");
+}
+function stripJsoncSyntax(source) {
+	let output = "";
+	let inString = false;
+	let escaped = false;
+	for (let index = 0; index < source.length; index += 1) {
+		const char = source[index];
+		const next = source[index + 1];
+		if (inString) {
+			output += char;
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			output += char;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			output += "  ";
+			index += 2;
+			while (index < source.length && source[index] !== "\n" && source[index] !== "\r") {
+				output += " ";
+				index += 1;
+			}
+			index -= 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			output += "  ";
+			index += 2;
+			while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) {
+				output += source[index] === "\n" || source[index] === "\r" ? source[index] : " ";
+				index += 1;
+			}
+			if (index < source.length) {
+				output += "  ";
+				index += 1;
+			}
+			continue;
+		}
+		if (char === "," && isTrailingJsonComma(source, index + 1)) {
+			output += " ";
+			continue;
+		}
+		output += char;
+	}
+	return output;
+}
+function isTrailingJsonComma(source, startIndex) {
+	let index = startIndex;
+	while (index < source.length) {
+		const char = source[index];
+		const next = source[index + 1];
+		if (/\s/u.test(char)) {
+			index += 1;
+			continue;
+		}
+		if (char === "/" && next === "/") {
+			index += 2;
+			while (index < source.length && source[index] !== "\n" && source[index] !== "\r") index += 1;
+			continue;
+		}
+		if (char === "/" && next === "*") {
+			index += 2;
+			while (index < source.length && !(source[index] === "*" && source[index + 1] === "/")) index += 1;
+			index += 2;
+			continue;
+		}
+		return char === "}" || char === "]";
+	}
+	return false;
+}
 function parseConfigFile(path, value) {
 	const raw = rawTopchesterConfigSchema.safeParse(value ?? {});
 	if (!raw.success) throw new Error(`Invalid Topchester config at ${path}: ${raw.error.issues.map(formatZodIssue).join("; ")}`);
@@ -6041,7 +6157,7 @@ function normalizeLogLevel(level) {
 //#endregion
 //#region src/app/context.ts
 function createAppContext(options) {
-	ensureGlobalTopchesterConfigDir();
+	ensureGlobalTopchesterConfigFile();
 	const config = loadTopchesterConfig(options);
 	const modelGateway = createModelGatewayFromConfig(config);
 	const loggerInfo = createTopchesterLogger(options.workspaceRoot);
@@ -12050,6 +12166,11 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 				else {
 					const approval = await this.resolveBashApproval(executableToolCall, toolCall.id, options, session, abortSignal);
 					for (const event of approval.events) yield event;
+					if (approval.cancelled && approval.stopped) {
+						if (!approval.events.some((event) => event.type === "message" && event.text === approval.reason)) yield agentEvent.systemMessage(approval.reason);
+						yield agentEvent.status("ready");
+						return;
+					}
 					if (approval.cancelled) toolResult = createToolErrorResult(executableToolCall.tool, approval.reason);
 					else {
 						const toolEventQueue = createRuntimeEventQueue();
@@ -12293,9 +12414,15 @@ var TopchesterAgentRuntime = class TopchesterAgentRuntime {
 			abortSignal
 		});
 		const events = this.hookResultToEvents(actionRequiredHook);
-		if (actionRequiredHook.blocked || actionRequiredHook.stopped) return {
+		if (actionRequiredHook.stopped) return {
+			cancelled: true,
+			stopped: true,
+			reason: actionRequiredHook.stopped.message,
+			events
+		};
+		if (actionRequiredHook.blocked) return {
 			cancelled: true,
-			reason: (actionRequiredHook.blocked ?? actionRequiredHook.stopped).message,
+			reason: actionRequiredHook.blocked.message,
 			events
 		};
 		const approval = await options.requestBashApproval({
@@ -13963,6 +14090,142 @@ function defaultSelfUpdateCheckRunner(command, args) {
 	});
 }
 //#endregion
+//#region src/cli/info.ts
+async function collectTopchesterInfo(options) {
+	const sources = getTopchesterConfigSources(options);
+	const lines = [
+		color("Topchester info", "cyan"),
+		"",
+		section("summary"),
+		row("version", getTopchesterVersion()),
+		row("workspace", formatInfoPath(options.workspaceRoot)),
+		"",
+		section("config"),
+		...sources.map((source) => {
+			if (!source.path) return row(formatConfigSourceLabel(source.label), status("unset", "muted"));
+			return row(formatConfigSourceLabel(source.label), `${formatInfoPath(source.path)} ${statusBadge(source.exists)}`);
+		})
+	];
+	let config;
+	try {
+		config = loadTopchesterConfig(options);
+	} catch (error) {
+		lines.push(row("status", status("invalid", "bad")), row("error", ui.error(formatInfoError(error))));
+		return {
+			ok: false,
+			lines
+		};
+	}
+	lines.push(row("status", status("valid", "good")), "", ...formatModelHints(config), "", ...formatProviderHints(config));
+	lines.push("", ...formatMcpHints(config), "", ...formatHooksHints(config), "", ...formatPathHints(options));
+	if (options.devFlags && options.devFlags.length > 0) lines.push("", section("dev"), row("flags", options.devFlags.join(", ")));
+	return {
+		ok: true,
+		lines
+	};
+}
+function formatModelHints(config) {
+	const assignments = config.models?.assignments ?? {};
+	const purposes = Object.keys(assignments).sort();
+	if (purposes.length === 0) return [
+		section("models"),
+		row("configured", status("none", "muted")),
+		row("hint", "run /connect openrouter, then /model")
+	];
+	return [
+		section("models"),
+		row("default purpose", config.models?.defaultPurpose ?? "agent.primary"),
+		...purposes.map((purpose) => row(purpose, ui.model(formatModelRef(assignments[purpose]))))
+	];
+}
+function formatProviderHints(config) {
+	const providers = config.models?.providers ?? {};
+	const namedProviders = Object.entries(providers).filter(([providerId]) => providerId !== "default");
+	if (namedProviders.length === 0) return [section("providers"), row("configured", status("none", "muted"))];
+	const lines = [section("providers")];
+	if (typeof providers.default === "string") lines.push(row("default", providers.default));
+	for (const [providerId, provider] of namedProviders) {
+		if (typeof provider === "string") continue;
+		const auth = provider.apiKeyEnv ? `env:${provider.apiKeyEnv} ${statusBadge(Boolean(process.env[provider.apiKeyEnv]), "set")}` : provider.apiKey ? status("inline", "good") : status("none", "muted");
+		lines.push(row(providerId, `${provider.type} ${provider.baseURL} auth=${auth}`));
+	}
+	return lines;
+}
+function formatMcpHints(config) {
+	const servers = Object.entries(config.mcp ?? {});
+	if (servers.length === 0) return [section("mcp"), row("servers", status("none", "muted"))];
+	return [section("mcp"), ...servers.map(([serverName, server]) => {
+		const tools = server.enabledTools && server.enabledTools.length > 0 ? server.enabledTools.join(",") : "all under cap";
+		const commandFound = Boolean(findExecutable(server.command));
+		return row(serverName, `${server.enabled === false ? status("disabled", "muted") : status("enabled", "good")} command=${server.command} ${statusBadge(commandFound, "found")} tools=${tools}`);
+	})];
+}
+function formatHooksHints(config) {
+	const hooks = config.hooks ?? {};
+	const hookEntries = Object.entries(hooks).filter((entry) => Array.isArray(entry[1]) && entry[1].length > 0);
+	const commandCount = hookEntries.reduce((count, [, commands]) => count + commands.length, 0);
+	if (commandCount === 0) return [section("hooks"), row("commands", status("none", "muted"))];
+	return [
+		section("hooks"),
+		row("events", String(hookEntries.length)),
+		row("commands", String(commandCount))
+	];
+}
+function formatPathHints(options) {
+	const knowledgePath = join(options.workspaceRoot, "topchester-kb");
+	return [
+		section("paths"),
+		row("sessions", formatInfoPath(getTopchesterSessionsPath(options.workspaceRoot))),
+		row("log file", formatInfoPath(getTopchesterLogFilePath(options.workspaceRoot))),
+		row("knowledge", `${formatInfoPath(knowledgePath)} ${statusBadge(existsSync(knowledgePath))}`)
+	];
+}
+function section(title) {
+	return color(`${title}:`, "cyan");
+}
+function row(label, value) {
+	return `  ${ui.label(label)}: ${value}`;
+}
+function statusBadge(ok, okText = "ok") {
+	return `[${status(ok ? okText : "missing", ok ? "good" : "warn")}]`;
+}
+function status(text, tone) {
+	switch (tone) {
+		case "good": return ui.ok(text);
+		case "warn": return ui.warn(text);
+		case "bad": return ui.error(text);
+		case "muted": return ui.muted(text);
+	}
+}
+function formatConfigSourceLabel(label) {
+	return label === "env" ? "env TOPCHESTER_CONFIG" : label === "cli" ? "cli --config" : label;
+}
+function findExecutable(command) {
+	if (command.includes("/") || isAbsolute(command)) return canExecute(command) ? command : void 0;
+	for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+		if (!dir) continue;
+		const candidate = resolve(dir, command);
+		if (canExecute(candidate)) return candidate;
+	}
+}
+function canExecute(path) {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function formatInfoPath(path) {
+	const homeRelative = relative(homedir(), path);
+	if (!homeRelative) return "~";
+	if (!homeRelative.startsWith("..") && !isAbsolute(homeRelative)) return `~/${homeRelative}`;
+	return path;
+}
+function formatInfoError(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/cli.ts
 async function runTopchesterCli(argv = process.argv, options = {}) {
 	const program = createTopchesterProgram();
@@ -13999,6 +14262,11 @@ function createTopchesterProgram() {
 		console.log("Topchester local dev mode");
 		printStartupSummary(context);
 	});
+	program.command("info").description("show config and local runtime hints").action(async () => {
+		const result = await collectTopchesterInfo(getContextOptionsFromProgram(program));
+		console.log(result.lines.join("\n"));
+		if (!result.ok) process.exitCode = 1;
+	});
 	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();
@@ -14105,12 +14373,15 @@ function printStartupSummary(context) {
 	}
 }
 function createContextFromOptions(program) {
+	return createAppContext(getContextOptionsFromProgram(program));
+}
+function getContextOptionsFromProgram(program) {
 	const options = program.opts();
-	return createAppContext({
+	return {
 		workspaceRoot: options.workspace,
 		configPath: options.config && (isAbsolute(options.config) ? options.config : resolve(cwd(), options.config)),
 		devFlags: options.dev
-	});
+	};
 }
 async function executeKbSearchCommand(program, queryParts, options) {
 	const context = createContextFromOptions(program);
@@ -14163,4 +14434,4 @@ function formatDryRunSyncStatus(status) {
 //#endregion
 export { runTopchesterCli as t };
 
-//# sourceMappingURL=cli-CVWQPq7z.mjs.map
+//# sourceMappingURL=cli-BgMj4Ifj.mjs.map