mini-coder 0.5.14 → 0.6.0

package/src/settings.ts

@@ -1,449 +0,0 @@
-/**
- * User settings persistence and startup resolution.
- *
- * Stores global defaults such as model, effort, reasoning visibility,
- * verbose tool output, custom providers, and MCP server settings in a JSON
- * file under the app data directory.
- *
- * @module
- */
-
-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 {
-  /** Provider identifier, e.g. "ollama". Shown as the provider prefix in model names. */
-  name: string;
-  /** OpenAI-compatible API base URL, e.g. "http://localhost:11434/v1". */
-  baseUrl: string;
-  /** Optional API key. Defaults to "no-key" at discovery time. */
-  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";
-
-/** Default reasoning visibility when no saved setting exists. */
-export const DEFAULT_SHOW_REASONING = true;
-
-/** Default verbose tool rendering flag when no saved setting exists. */
-export const DEFAULT_VERBOSE = false;
-
-/** Persisted global user settings. */
-export interface UserSettings {
-  /** Preferred provider/model identifier. */
-  defaultModel?: string;
-  /** Preferred reasoning effort. */
-  defaultEffort?: ThinkingLevel;
-  /** Whether reasoning blocks are shown in the UI. */
-  showReasoning?: boolean;
-  /** Whether full tool output is shown in the UI. */
-  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. */
-interface StartupSettings {
-  /** Model to use for this launch, or `null` if none are available. */
-  modelId: string | null;
-  /** Effective reasoning effort. */
-  effort: ThinkingLevel;
-  /** Effective reasoning visibility. */
-  showReasoning: boolean;
-  /** Effective verbose flag. */
-  verbose: boolean;
-}
-
-const THINKING_LEVELS = new Set<ThinkingLevel>([
-  "low",
-  "medium",
-  "high",
-  "xhigh",
-]);
-
-const MCP_SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
-
-/**
- * Load and validate user settings from disk.
- *
- * Missing files are treated as empty settings. Invalid JSON or unreadable files
- * fail with a descriptive error instead of silently discarding saved state.
- *
- * @param path - Absolute path to `settings.json`.
- * @returns The validated settings object.
- */
-export function loadSettings(path: string): UserSettings {
-  if (!existsSync(path)) {
-    return {};
-  }
-
-  try {
-    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) {
-    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;
-}
-
-/**
- * Save user settings to disk.
- *
- * Parent directories are created automatically. Only validated fields are
- * written to disk.
- *
- * @param path - Absolute path to `settings.json`.
- * @param settings - Settings to persist.
- * @returns The validated settings that were written.
- */
-export function saveSettings(
-  path: string,
-  settings: UserSettings,
-): UserSettings {
-  const sanitized = sanitizeSettings(settings);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, JSON.stringify(sanitized, null, 2), "utf-8");
-  return sanitized;
-}
-
-/**
- * Merge a partial settings update with the current file contents and persist it.
- *
- * Invalid fields in the update are ignored.
- *
- * @param path - Absolute path to `settings.json`.
- * @param update - Partial settings update to merge.
- * @returns The merged settings after persistence.
- */
-export function updateSettings(
-  path: string,
-  update: Partial<UserSettings>,
-): UserSettings {
-  const current = loadSettings(path);
-  const merged = mergeUserSettings(current, sanitizeSettings(update));
-  return saveSettings(path, merged);
-}
-
-/**
- * Resolve the effective startup settings for the current launch.
- *
- * The saved preferred model is only used when it is currently available.
- * Otherwise the first available model is used for this launch, while the saved
- * preference remains unchanged on disk.
- *
- * @param settings - Saved user settings.
- * @param availableModelIds - Provider/model identifiers available this launch.
- * @returns Effective startup settings with fallbacks applied.
- */
-export function resolveStartupSettings(
-  settings: UserSettings,
-  availableModelIds: readonly string[],
-): StartupSettings {
-  const preferredModel = settings.defaultModel;
-  const modelId =
-    preferredModel && availableModelIds.includes(preferredModel)
-      ? preferredModel
-      : (availableModelIds[0] ?? null);
-
-  return {
-    modelId,
-    effort: settings.defaultEffort ?? DEFAULT_EFFORT,
-    showReasoning: settings.showReasoning ?? DEFAULT_SHOW_REASONING,
-    verbose: settings.verbose ?? DEFAULT_VERBOSE,
-  };
-}
-
-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.
- *
- * Unknown or invalid fields are dropped.
- *
- * @param value - Parsed JSON value.
- * @returns Sanitized settings.
- */
-function sanitizeSettings(value: unknown): UserSettings {
-  const candidate = toRecord(value);
-  if (!candidate) {
-    return {};
-  }
-
-  const settings: UserSettings = {};
-  const defaultModel = readString(candidate, "defaultModel");
-  const showReasoning = readBoolean(candidate, "showReasoning");
-  const verbose = readBoolean(candidate, "verbose");
-
-  if (defaultModel !== null) {
-    settings.defaultModel = defaultModel;
-  }
-  if (isThinkingLevel(candidate.defaultEffort)) {
-    settings.defaultEffort = candidate.defaultEffort;
-  }
-  if (showReasoning !== null) {
-    settings.showReasoning = showReasoning;
-  }
-  if (verbose !== null) {
-    settings.verbose = verbose;
-  }
-
-  const customProviders = sanitizeCustomProviders(candidate.customProviders);
-  if (customProviders) {
-    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 {
-  const candidate = toRecord(item);
-  if (!candidate) {
-    return null;
-  }
-
-  const name = readString(candidate, "name")?.trim() ?? "";
-  const baseUrl = readString(candidate, "baseUrl")?.trim() ?? "";
-
-  if (!name || !baseUrl) {
-    return null;
-  }
-
-  const entry: CustomProvider = { name, baseUrl };
-  const apiKey = readString(candidate, "apiKey");
-  if (apiKey !== null) {
-    entry.apiKey = apiKey;
-  }
-  return entry;
-}
-
-/**
- * Validate and normalize custom provider entries.
- *
- * Drops entries with missing/empty name or baseUrl, and deduplicates by name
- * (first entry wins).
- */
-function sanitizeCustomProviders(value: unknown): CustomProvider[] | undefined {
-  if (!Array.isArray(value)) {
-    return undefined;
-  }
-
-  const result: CustomProvider[] = [];
-  const seen = new Set<string>();
-
-  for (const item of value) {
-    const entry = parseCustomProvider(item);
-    if (!entry || seen.has(entry.name)) {
-      continue;
-    }
-    seen.add(entry.name);
-    result.push(entry);
-  }
-
-  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.
- *
- * @param value - Value to validate.
- * @returns `true` when the value is a supported thinking level.
- */
-function isThinkingLevel(value: unknown): value is ThinkingLevel {
-  return (
-    typeof value === "string" && THINKING_LEVELS.has(value as ThinkingLevel)
-  );
-}

package/src/skills.ts

@@ -1,271 +0,0 @@
-/**
- * Agent Skills (agentskills.io) discovery, parsing, and catalog generation.
- *
- * Scans configured directories for `SKILL.md` files, extracts YAML
- * frontmatter (name, description), resolves name collisions (earlier
- * scan paths win), and generates an XML catalog string for inclusion
- * in the system prompt.
- *
- * @module
- */
-
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/**
- * A discovered agent skill.
- *
- * Represents a single SKILL.md file that has been parsed and is ready
- * for inclusion in the system prompt catalog.
- */
-export interface Skill {
-  /** Skill name (from frontmatter or directory name fallback). */
-  name: string;
-  /** Skill description (from frontmatter, empty if absent). */
-  description: string;
-  /** Absolute path to the SKILL.md file. */
-  path: string;
-}
-
-// ---------------------------------------------------------------------------
-// Frontmatter parsing
-// ---------------------------------------------------------------------------
-
-function getFrontmatterLines(content: string): string[] | null {
-  if (!content.startsWith("---")) {
-    return null;
-  }
-
-  const endIdx = content.indexOf("\n---", 3);
-  if (endIdx === -1) {
-    return null;
-  }
-
-  return content.slice(4, endIdx).split("\n");
-}
-
-function parseFrontmatterEntry(
-  line: string,
-): { key: string; value: string } | null {
-  const colonIdx = line.indexOf(":");
-  if (colonIdx === -1) {
-    return null;
-  }
-
-  return {
-    key: line.slice(0, colonIdx).trim(),
-    value: line.slice(colonIdx + 1).trim(),
-  };
-}
-
-function isIndentedFrontmatterLine(line: string): boolean {
-  return line.startsWith(" ") || line.startsWith("\t");
-}
-
-function readFoldedFrontmatterValue(
-  lines: string[],
-  startIndex: number,
-): string {
-  const folded: string[] = [];
-  for (let i = startIndex; i < lines.length; i++) {
-    const line = lines[i];
-    if (!line || !isIndentedFrontmatterLine(line)) {
-      break;
-    }
-    folded.push(line.trim());
-  }
-  return folded.join(" ");
-}
-
-function readDescriptionValue(
-  lines: string[],
-  lineIndex: number,
-  value: string,
-): string {
-  if (value === ">") {
-    return readFoldedFrontmatterValue(lines, lineIndex + 1);
-  }
-  return stripQuotes(value);
-}
-
-/**
- * Parse YAML frontmatter from a SKILL.md file's content.
- *
- * Handles simple key-value pairs, quoted strings, and YAML folded
- * scalars (`>`). Does not use a full YAML parser — just enough to
- * extract `name` and `description`.
- *
- * @param content - Raw file content.
- * @returns Extracted name and description (both may be undefined).
- */
-function parseFrontmatter(content: string): {
-  name: string | undefined;
-  description: string | undefined;
-} {
-  const lines = getFrontmatterLines(content);
-  if (!lines) {
-    return { name: undefined, description: undefined };
-  }
-
-  let name: string | undefined;
-  let description: string | undefined;
-
-  for (const [index, line] of lines.entries()) {
-    const entry = parseFrontmatterEntry(line);
-    if (!entry) {
-      continue;
-    }
-    if (entry.key === "name") {
-      name = stripQuotes(entry.value);
-      continue;
-    }
-    if (entry.key === "description") {
-      description = readDescriptionValue(lines, index, entry.value);
-    }
-  }
-
-  return { name, description };
-}
-
-/**
- * Strip surrounding single or double quotes from a string.
- *
- * @param s - The string to strip.
- * @returns The string without surrounding quotes.
- */
-function stripQuotes(s: string): string {
-  if (s.length >= 2) {
-    if (
-      (s[0] === '"' && s[s.length - 1] === '"') ||
-      (s[0] === "'" && s[s.length - 1] === "'")
-    ) {
-      return s.slice(1, -1);
-    }
-  }
-  return s;
-}
-
-// ---------------------------------------------------------------------------
-// Discovery
-// ---------------------------------------------------------------------------
-
-function listSkillEntries(basePath: string): string[] {
-  if (!existsSync(basePath)) {
-    return [];
-  }
-  try {
-    return readdirSync(basePath);
-  } catch {
-    return [];
-  }
-}
-
-function isDirectory(path: string): boolean {
-  try {
-    return statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function readSkill(basePath: string, entry: string): Skill | null {
-  const dir = join(basePath, entry);
-  if (!isDirectory(dir)) {
-    return null;
-  }
-
-  const skillPath = join(dir, "SKILL.md");
-  if (!existsSync(skillPath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(skillPath, "utf-8");
-    const frontmatter = parseFrontmatter(content);
-    return {
-      name: frontmatter.name ?? entry,
-      description: frontmatter.description ?? "",
-      path: skillPath,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Discover agent skills from the given scan paths.
- *
- * Scans each path for subdirectories containing a `SKILL.md` file.
- * Earlier paths in the array have higher priority — on name collision,
- * the first-seen skill wins (project-level over user-level).
- *
- * @param scanPaths - Ordered directories to scan (project paths first).
- * @returns Array of discovered {@link Skill} records, deduplicated by name.
- */
-export function discoverSkills(scanPaths: string[]): Skill[] {
-  const seen = new Map<string, Skill>();
-
-  for (const basePath of scanPaths) {
-    for (const entry of listSkillEntries(basePath)) {
-      const skill = readSkill(basePath, entry);
-      if (!skill || seen.has(skill.name)) {
-        continue;
-      }
-      seen.set(skill.name, skill);
-    }
-  }
-
-  return [...seen.values()];
-}
-
-// ---------------------------------------------------------------------------
-// Catalog generation
-// ---------------------------------------------------------------------------
-
-function escapeXml(value: string): string {
-  return value
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&apos;");
-}
-
-/**
- * Build the XML skill catalog for the system prompt.
- *
- * Returns the full catalog section including the preamble text and
- * `<available_skills>` XML block. Returns an empty string if no
- * skills are provided.
- *
- * @param skills - Discovered skills to include.
- * @returns The catalog string to append to the system prompt.
- */
-export function buildSkillCatalog(skills: Skill[]): string {
-  if (skills.length === 0) return "";
-
-  const entries = skills
-    .map(
-      (s) =>
-        `  <skill>\n` +
-        `    <name>${escapeXml(s.name)}</name>\n` +
-        `    <description>${escapeXml(s.description)}</description>\n` +
-        `    <location>${escapeXml(s.path)}</location>\n` +
-        `  </skill>`,
-    )
-    .join("\n");
-
-  return (
-    `The following skills provide specialized instructions for specific tasks.\n` +
-    `Use the shell tool to read a skill's file when the task matches its description.\n` +
-    `When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md) and use that absolute path in tool commands.\n` +
-    `\n` +
-    `<available_skills>\n` +
-    entries +
-    `\n</available_skills>`
-  );
-}