mini-coder 0.5.11 → 0.5.13

package/src/settings.ts

@@ -2,7 +2,8 @@
  * User settings persistence and startup resolution.
  *
  * Stores global defaults such as model, effort, reasoning visibility,
- * and verbose tool output in a JSON file under the app data directory.
+ * verbose tool output, custom providers, and MCP server settings in a JSON
+ * file under the app data directory.
  *
  * @module
  */
@@ -11,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import type { ThinkingLevel } from "@mariozechner/pi-ai";
 import { getErrorMessage } from "./errors.ts";
+import { readBoolean, readString, toRecord } from "./shared.ts";
 
 /** A user-configured OpenAI-compatible provider endpoint. */
 export interface CustomProvider {
@@ -22,6 +24,22 @@ export interface CustomProvider {
   apiKey?: string;
 }
 
+/** A single configured MCP server endpoint. */
+export interface McpServerConfig {
+  /** Stable server identifier. Used as the imported tool-name prefix. */
+  name: string;
+  /** Absolute Streamable HTTP MCP endpoint URL. */
+  url: string;
+  /** Whether the server should start enabled. */
+  enabled: boolean;
+}
+
+/** MCP-related user settings. */
+export interface McpSettings {
+  /** MCP servers to connect to at startup. */
+  servers?: McpServerConfig[];
+}
+
 /** Default reasoning effort when no saved setting exists. */
 const DEFAULT_EFFORT: ThinkingLevel = "medium";
 
@@ -43,6 +61,8 @@ export interface UserSettings {
   verbose?: boolean;
   /** Custom OpenAI-compatible provider endpoints. */
   customProviders?: CustomProvider[];
+  /** MCP server definitions to manage and connect when enabled. */
+  mcp?: McpSettings;
 }
 
 /** Resolved startup settings after applying defaults and availability checks. */
@@ -64,6 +84,8 @@ const THINKING_LEVELS = new Set<ThinkingLevel>([
   "xhigh",
 ]);
 
+const MCP_SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+
 /**
  * Load and validate user settings from disk.
  *
@@ -79,13 +101,81 @@ export function loadSettings(path: string): UserSettings {
   }
 
   try {
-    const raw = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-    return sanitizeSettings(raw);
+    return parseSettingsFile(path);
+  } catch (error) {
+    throw createSettingsReadError(path, error);
+  }
+}
+
+/**
+ * Load settings for startup without aborting on invalid JSON.
+ *
+ * Missing files and invalid JSON content are treated as empty settings so
+ * startup behaves like there are no saved settings. Other filesystem errors
+ * still fail with the same descriptive read error as {@link loadSettings}.
+ *
+ * @param path - Absolute path to `settings.json`.
+ * @returns The validated settings object, or `{}` when startup should ignore invalid JSON.
+ */
+export function loadStartupSettings(path: string): UserSettings {
+  if (!existsSync(path)) {
+    return {};
+  }
+
+  try {
+    return parseSettingsFile(path);
   } catch (error) {
-    throw new Error(
-      `Failed to read settings ${path}: ${getErrorMessage(error)}`,
-    );
+    if (error instanceof SyntaxError) {
+      return {};
+    }
+    throw createSettingsReadError(path, error);
+  }
+}
+
+/**
+ * Merge two settings objects using startup overlay semantics.
+ *
+ * Scalar fields use override-wins. `customProviders` merges by provider name,
+ * and `mcp.servers` merges by server name. Same-name override entries replace
+ * base entries while keeping the base ordering stable; new override entries are
+ * appended in override order.
+ *
+ * @param base - Base settings, usually the global settings file.
+ * @param override - Higher-priority settings, usually a repo-local overlay.
+ * @returns The merged effective settings.
+ */
+export function mergeUserSettings(
+  base: UserSettings,
+  override: UserSettings,
+): UserSettings {
+  const sanitizedBase = sanitizeSettings(base);
+  const sanitizedOverride = sanitizeSettings(override);
+  const merged: UserSettings = {
+    ...sanitizedBase,
+    ...sanitizedOverride,
+  };
+
+  const customProviders = mergeNamedEntries(
+    sanitizedBase.customProviders,
+    sanitizedOverride.customProviders,
+  );
+  if (customProviders) {
+    merged.customProviders = customProviders;
+  } else {
+    delete merged.customProviders;
+  }
+
+  const servers = mergeNamedEntries(
+    sanitizedBase.mcp?.servers,
+    sanitizedOverride.mcp?.servers,
+  );
+  if (servers) {
+    merged.mcp = { servers };
+  } else {
+    delete merged.mcp;
   }
+
+  return merged;
 }
 
 /**
@@ -122,7 +212,7 @@ export function updateSettings(
   update: Partial<UserSettings>,
 ): UserSettings {
   const current = loadSettings(path);
-  const merged = { ...current, ...sanitizeSettings(update) };
+  const merged = mergeUserSettings(current, sanitizeSettings(update));
   return saveSettings(path, merged);
 }
 
@@ -155,6 +245,46 @@ export function resolveStartupSettings(
   };
 }
 
+function mergeNamedEntries<T extends { name: string }>(
+  base: readonly T[] | undefined,
+  override: readonly T[] | undefined,
+): T[] | undefined {
+  if (!base?.length && !override?.length) {
+    return undefined;
+  }
+
+  const merged = [...(base ?? [])];
+  const indexes = new Map<string, number>();
+
+  for (const [index, entry] of merged.entries()) {
+    indexes.set(entry.name, index);
+  }
+
+  for (const entry of override ?? []) {
+    const existingIndex = indexes.get(entry.name);
+    if (existingIndex === undefined) {
+      indexes.set(entry.name, merged.length);
+      merged.push(entry);
+      continue;
+    }
+
+    merged[existingIndex] = entry;
+  }
+
+  return merged.length > 0 ? merged : undefined;
+}
+
+function parseSettingsFile(path: string): UserSettings {
+  const raw = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+  return sanitizeSettings(raw);
+}
+
+function createSettingsReadError(path: string, error: unknown): Error {
+  return new Error(
+    `Failed to read settings ${path}: ${getErrorMessage(error)}`,
+  );
+}
+
 /**
  * Validate and normalize a parsed settings object.
  *
@@ -164,24 +294,27 @@ export function resolveStartupSettings(
  * @returns Sanitized settings.
  */
 function sanitizeSettings(value: unknown): UserSettings {
-  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+  const candidate = toRecord(value);
+  if (!candidate) {
     return {};
   }
 
-  const candidate = value as Record<string, unknown>;
   const settings: UserSettings = {};
+  const defaultModel = readString(candidate, "defaultModel");
+  const showReasoning = readBoolean(candidate, "showReasoning");
+  const verbose = readBoolean(candidate, "verbose");
 
-  if (typeof candidate.defaultModel === "string") {
-    settings.defaultModel = candidate.defaultModel;
+  if (defaultModel !== null) {
+    settings.defaultModel = defaultModel;
   }
   if (isThinkingLevel(candidate.defaultEffort)) {
     settings.defaultEffort = candidate.defaultEffort;
   }
-  if (typeof candidate.showReasoning === "boolean") {
-    settings.showReasoning = candidate.showReasoning;
+  if (showReasoning !== null) {
+    settings.showReasoning = showReasoning;
   }
-  if (typeof candidate.verbose === "boolean") {
-    settings.verbose = candidate.verbose;
+  if (verbose !== null) {
+    settings.verbose = verbose;
   }
 
   const customProviders = sanitizeCustomProviders(candidate.customProviders);
@@ -189,27 +322,32 @@ function sanitizeSettings(value: unknown): UserSettings {
     settings.customProviders = customProviders;
   }
 
+  const mcp = sanitizeMcpSettings(candidate.mcp);
+  if (mcp) {
+    settings.mcp = mcp;
+  }
+
   return settings;
 }
 
 /** Try to parse a single custom provider entry, returning null on failure. */
 function parseCustomProvider(item: unknown): CustomProvider | null {
-  if (item == null || typeof item !== "object" || Array.isArray(item)) {
+  const candidate = toRecord(item);
+  if (!candidate) {
     return null;
   }
 
-  const candidate = item as Record<string, unknown>;
-  const name = typeof candidate.name === "string" ? candidate.name.trim() : "";
-  const baseUrl =
-    typeof candidate.baseUrl === "string" ? candidate.baseUrl.trim() : "";
+  const name = readString(candidate, "name")?.trim() ?? "";
+  const baseUrl = readString(candidate, "baseUrl")?.trim() ?? "";
 
   if (!name || !baseUrl) {
     return null;
   }
 
   const entry: CustomProvider = { name, baseUrl };
-  if (typeof candidate.apiKey === "string") {
-    entry.apiKey = candidate.apiKey;
+  const apiKey = readString(candidate, "apiKey");
+  if (apiKey !== null) {
+    entry.apiKey = apiKey;
   }
   return entry;
 }
@@ -240,6 +378,64 @@ function sanitizeCustomProviders(value: unknown): CustomProvider[] | undefined {
   return result.length > 0 ? result : undefined;
 }
 
+function sanitizeMcpSettings(value: unknown): McpSettings | undefined {
+  const candidate = toRecord(value);
+  if (!candidate) {
+    return undefined;
+  }
+
+  const servers = sanitizeMcpServers(candidate.servers);
+  if (!servers) {
+    return undefined;
+  }
+
+  return { servers };
+}
+
+/** Try to parse a single MCP server entry, returning null on failure. */
+function parseMcpServer(item: unknown): McpServerConfig | null {
+  const candidate = toRecord(item);
+  if (!candidate) {
+    return null;
+  }
+
+  const name = readString(candidate, "name")?.trim() ?? "";
+  const url = readString(candidate, "url")?.trim() ?? "";
+  const enabled = readBoolean(candidate, "enabled") ?? true;
+
+  if (!name || !url || !MCP_SERVER_NAME_PATTERN.test(name)) {
+    return null;
+  }
+
+  return { name, url, enabled };
+}
+
+/**
+ * Validate and normalize configured MCP servers.
+ *
+ * Drops entries with missing/invalid names or URLs, and deduplicates by name
+ * (first entry wins).
+ */
+function sanitizeMcpServers(value: unknown): McpServerConfig[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  const result: McpServerConfig[] = [];
+  const seen = new Set<string>();
+
+  for (const item of value) {
+    const entry = parseMcpServer(item);
+    if (!entry || seen.has(entry.name)) {
+      continue;
+    }
+    seen.add(entry.name);
+    result.push(entry);
+  }
+
+  return result.length > 0 ? result : undefined;
+}
+
 /**
  * Check whether a value is a valid thinking level.
  *

package/src/shared.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared runtime record/primitive readers used across the app.
+ *
+ * @module
+ */
+
+/** Convert an unknown value into a plain record, rejecting arrays and null. */
+export function toRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/** Read a string field from a record, returning null for missing or invalid values. */
+export function readString(
+  record: Record<string, unknown>,
+  key: string,
+): string | null {
+  const value = record[key];
+  return typeof value === "string" ? value : null;
+}
+
+/** Read a boolean field from a record, returning null for missing or invalid values. */
+export function readBoolean(
+  record: Record<string, unknown>,
+  key: string,
+): boolean | null {
+  const value = record[key];
+  return typeof value === "boolean" ? value : null;
+}
+
+/** Read a finite numeric field from a record, returning null for missing or invalid values. */
+export function readFiniteNumber(
+  record: Record<string, unknown>,
+  key: string,
+): number | null {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}

package/src/skills.ts

@@ -226,6 +226,15 @@ export function discoverSkills(scanPaths: string[]): Skill[] {
 // Catalog generation
 // ---------------------------------------------------------------------------
 
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&apos;");
+}
+
 /**
  * Build the XML skill catalog for the system prompt.
  *
@@ -243,9 +252,9 @@ export function buildSkillCatalog(skills: Skill[]): string {
     .map(
       (s) =>
         `  <skill>\n` +
-        `    <name>${s.name}</name>\n` +
-        `    <description>${s.description}</description>\n` +
-        `    <location>${s.path}</location>\n` +
+        `    <name>${escapeXml(s.name)}</name>\n` +
+        `    <description>${escapeXml(s.description)}</description>\n` +
+        `    <location>${escapeXml(s.path)}</location>\n` +
         `  </skill>`,
     )
     .join("\n");

package/src/submit.ts

@@ -18,8 +18,7 @@ import {
 } from "./index.ts";
 import { parseInput } from "./input.ts";
 import {
-  addMessageToContextTokens,
-  addMessageToStats,
+  appendConversationMessage,
   appendMessage,
   appendPromptHistory,
   filterModelMessages,
@@ -216,6 +215,20 @@ function recordRawPromptHistory(
   truncatePromptHistory(state.db, MAX_PROMPT_HISTORY);
 }
 
+/**
+ * Drop any resolved steering messages still queued on the active app state.
+ *
+ * Raw prompt-history rows are intentionally left untouched because queue resets
+ * must not rewrite global input-history behavior.
+ *
+ * @param state - Mutable application state containing the queued steering list.
+ */
+export function clearQueuedUserMessages(
+  state: Pick<AppState, "queuedUserMessages">,
+): void {
+  state.queuedUserMessages.length = 0;
+}
+
 /**
  * Queue resolved user content for the next model-request boundary of an active run.
  *
@@ -254,26 +267,9 @@ export function queueResolvedInput(
 function handleAgentEvent(event: AgentEvent, state: AppState): void {
   switch (event.type) {
     case "user_message":
-      state.messages.push(event.message);
-      state.contextTokens = addMessageToContextTokens(
-        state.contextTokens,
-        event.message,
-      );
-      break;
     case "assistant_message":
-      state.messages.push(event.message);
-      state.stats = addMessageToStats(state.stats, event.message);
-      state.contextTokens = addMessageToContextTokens(
-        state.contextTokens,
-        event.message,
-      );
-      break;
     case "tool_result":
-      state.messages.push(event.message);
-      state.contextTokens = addMessageToContextTokens(
-        state.contextTokens,
-        event.message,
-      );
+      appendConversationMessage(state, event.message);
       break;
     case "text_delta":
     case "thinking_delta":
@@ -319,6 +315,8 @@ export async function submitResolvedInput(
     throw new Error("Cannot submit empty input.");
   }
 
+  clearQueuedUserMessages(state);
+
   const session = ensureSession(state);
   recordRawPromptHistory(rawInput, state, session.id);
 
@@ -329,11 +327,7 @@ export async function submitResolvedInput(
   } satisfies UserMessage;
 
   const turn = appendMessage(state.db, session.id, userMessage);
-  state.messages.push(userMessage);
-  state.contextTokens = addMessageToContextTokens(
-    state.contextTokens,
-    userMessage,
-  );
+  appendConversationMessage(state, userMessage);
   hooks?.onUserMessage?.(state);
 
   const systemPrompt = buildPrompt(state);
@@ -369,6 +363,7 @@ export async function submitResolvedInput(
     stopReason = result.stopReason;
     return result.stopReason;
   } finally {
+    clearQueuedUserMessages(state);
     state.running = false;
     state.abortController = null;
     hooks?.onTurnEnd?.(state, stopReason);

package/src/text.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared text-shaping helpers.
+ *
+ * @module
+ */
+
+/**
+ * Collapse whitespace runs to single spaces and trim the ends.
+ *
+ * @param text - Raw text to normalize.
+ * @returns The collapsed single-line text.
+ */
+export function collapseWhitespace(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Collapse whitespace into a single line, returning `null` when nothing remains.
+ *
+ * @param text - Raw text to normalize.
+ * @returns Collapsed text, or `null` when the result is empty.
+ */
+export function collapseWhitespaceToNull(text: string): string | null {
+  const collapsed = collapseWhitespace(text);
+  return collapsed.length > 0 ? collapsed : null;
+}
+
+/**
+ * Join only `text` blocks from multipart content into one space-separated string.
+ *
+ * @param content - Multipart content blocks.
+ * @returns Concatenated text-block content.
+ */
+export function joinTextBlocks<T extends { type: string }>(
+  content: readonly T[],
+): string {
+  return content
+    .flatMap((block) => {
+      return block.type === "text" &&
+        "text" in block &&
+        typeof block.text === "string"
+        ? [block.text]
+        : [];
+    })
+    .join(" ");
+}
+
+/**
+ * Truncate text with an ellipsis from the start or end.
+ *
+ * @param text - Text to truncate.
+ * @param maxChars - Maximum visible characters including the ellipsis.
+ * @param side - Which side to truncate from.
+ * @returns Truncated text when needed.
+ */
+export function truncateText(
+  text: string,
+  maxChars: number,
+  side: "start" | "end" = "end",
+): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+  if (maxChars <= 1) {
+    return "…";
+  }
+  if (side === "start") {
+    return `…${text.slice(text.length - (maxChars - 1))}`;
+  }
+  return `${text.slice(0, maxChars - 1)}…`;
+}