mini-coder 0.4.1 → 0.5.0

package/src/input.ts

@@ -0,0 +1,155 @@
+/**
+ * User input parsing.
+ *
+ * Pure logic for detecting slash commands, skill references, image paths,
+ * and plain text from raw user input. No UI or IO beyond `existsSync`
+ * for image path validation.
+ *
+ * @module
+ */
+
+import { existsSync } from "node:fs";
+import { extname, isAbsolute, join } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** All recognized slash commands. */
+export const COMMANDS = [
+  "model",
+  "session",
+  "new",
+  "fork",
+  "undo",
+  "reasoning",
+  "verbose",
+  "login",
+  "logout",
+  "help",
+  "effort",
+] as const;
+
+/** A recognized slash command name. */
+type Command = (typeof COMMANDS)[number];
+
+const COMMAND_SET: ReadonlySet<string> = new Set(COMMANDS);
+
+/** Image file extensions we recognize for embedding. */
+const IMAGE_EXTENSIONS: ReadonlySet<string> = new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+]);
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Result of parsing user input. */
+type ParsedInput =
+  | { type: "command"; command: Command; args: string }
+  | { type: "skill"; skillName: string; userText: string }
+  | { type: "image"; path: string }
+  | { type: "text"; text: string };
+
+/** Options for input parsing. */
+interface ParseInputOpts {
+  /** Whether the current model supports image input. */
+  supportsImages?: boolean;
+  /** Working directory for resolving relative image paths. */
+  cwd?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+
+function isCommand(value: string): value is Command {
+  return COMMAND_SET.has(value);
+}
+
+function parseSlashInput(trimmed: string): ParsedInput | null {
+  const skillMatch = trimmed.match(/^\/skill:(\S+)(?:\s+(.*))?$/s);
+  if (skillMatch?.[1]) {
+    return {
+      type: "skill",
+      skillName: skillMatch[1],
+      userText: skillMatch[2]?.trim() ?? "",
+    };
+  }
+
+  const commandMatch = trimmed.match(/^\/(\S+)(?:\s+(.*))?$/s);
+  const command = commandMatch?.[1];
+  if (!command || !isCommand(command)) {
+    return null;
+  }
+
+  return {
+    type: "command",
+    command,
+    args: commandMatch[2]?.trim() ?? "",
+  };
+}
+
+function resolveImagePath(input: string, cwd?: string): string {
+  if (isAbsolute(input) || !cwd) {
+    return input;
+  }
+  return join(cwd, input);
+}
+
+function parseImageInput(
+  trimmed: string,
+  opts?: ParseInputOpts,
+): Extract<ParsedInput, { type: "image" }> | null {
+  if (!opts?.supportsImages) {
+    return null;
+  }
+  if (!IMAGE_EXTENSIONS.has(extname(trimmed).toLowerCase())) {
+    return null;
+  }
+
+  const resolvedPath = resolveImagePath(trimmed, opts.cwd);
+  if (!existsSync(resolvedPath)) {
+    return null;
+  }
+
+  return { type: "image", path: resolvedPath };
+}
+
+/**
+ * Parse raw user input into a structured result.
+ *
+ * Priority order:
+ * 1. Slash commands (`/model`, `/help`, etc.)
+ * 2. Skill references (`/skill:name rest of message`)
+ * 3. Image paths (entire input is an existing image file)
+ * 4. Plain text
+ *
+ * @param raw - The raw input string from the user.
+ * @param opts - Optional parsing context (image support, cwd).
+ * @returns A {@link ParsedInput} describing what the input represents.
+ */
+export function parseInput(raw: string, opts?: ParseInputOpts): ParsedInput {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) {
+    return { type: "text", text: "" };
+  }
+
+  if (trimmed[0] === "/") {
+    const slashInput = parseSlashInput(trimmed);
+    if (slashInput) {
+      return slashInput;
+    }
+  }
+
+  const imageInput = parseImageInput(trimmed, opts);
+  if (imageInput) {
+    return imageInput;
+  }
+
+  return { type: "text", text: trimmed };
+}

package/src/paths.ts

@@ -0,0 +1,37 @@
+/**
+ * Filesystem path normalization helpers.
+ *
+ * Provides a small shared policy for path identity across the app:
+ * when paths are used for comparison or persistence, we canonicalize them
+ * to an absolute, symlink-resolved spelling.
+ *
+ * @module
+ */
+
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+/**
+ * Return the canonical absolute path for an existing filesystem entry.
+ *
+ * Canonicalization resolves `.`/`..` segments and follows symlinks,
+ * producing a stable spelling suitable for path equality checks and
+ * persistence keys.
+ *
+ * @param path - An existing filesystem path.
+ * @returns The canonical absolute path.
+ */
+export function canonicalizePath(path: string): string {
+  return realpathSync(resolve(path));
+}
+
+/**
+ * Check whether two paths refer to the same existing filesystem entry.
+ *
+ * @param a - The first path to compare.
+ * @param b - The second path to compare.
+ * @returns `true` when both paths resolve to the same canonical location.
+ */
+export function isSamePath(a: string, b: string): boolean {
+  return canonicalizePath(a) === canonicalizePath(b);
+}

package/src/plugins.ts

@@ -0,0 +1,183 @@
+/**
+ * Plugin loader and lifecycle management.
+ *
+ * Plugins extend mini-coder with additional tools and system prompt context.
+ * They are declared in a config file and loaded as modules at startup.
+ * Each plugin's `init` is called once, and `destroy` (if present) is called
+ * on shutdown.
+ *
+ * @module
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Message, Tool } from "@mariozechner/pi-ai";
+import type { ToolHandler } from "./agent.ts";
+import type { Theme } from "./theme.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Context provided to plugins during initialization.
+ *
+ * Gives plugins read-only access to the agent's environment without
+ * exposing internal implementation details.
+ */
+export interface AgentContext {
+  /** The working directory. */
+  cwd: string;
+  /** Read-only access to the current session's messages. */
+  messages: readonly Message[];
+  /** The app data directory (`~/.config/mini-coder/`). */
+  dataDir: string;
+}
+
+/**
+ * Result returned by a plugin's `init` function.
+ *
+ * Contains any additional tools the agent should register and/or
+ * context to append to the system prompt.
+ */
+export interface PluginResult {
+  /** Additional tool definitions to register with the model. */
+  tools?: Tool[];
+  /** Tool name → handler map for the tools above. */
+  toolHandlers?: Map<string, ToolHandler>;
+  /** Additional context to append to the system prompt. */
+  systemPromptSuffix?: string;
+  /** Partial theme override — merged on top of the default theme. */
+  theme?: Partial<Theme>;
+}
+
+/**
+ * The interface a plugin module must implement.
+ *
+ * A plugin is a module that exports a conforming object. It is loaded
+ * dynamically from a path or package name declared in the config file.
+ */
+export interface Plugin {
+  /** Human-readable plugin name. */
+  name: string;
+  /** Brief description of what the plugin provides. */
+  description: string;
+  /** Called once at startup. Returns tools to register and/or context to add. */
+  init(
+    agent: AgentContext,
+    config?: Record<string, unknown>,
+  ): Promise<PluginResult>;
+  /** Called on shutdown for cleanup. */
+  destroy?(): Promise<void>;
+}
+
+/** A single entry in the plugins config file. */
+export interface PluginEntry {
+  /** Plugin name (for display and error messages). */
+  name: string;
+  /** Module path or package name to import. */
+  module: string;
+  /** Optional configuration passed to the plugin's `init`. */
+  config?: Record<string, unknown>;
+}
+
+/** A loaded and initialized plugin with its result. */
+export interface LoadedPlugin {
+  /** The plugin entry from config. */
+  entry: PluginEntry;
+  /** The plugin module instance. */
+  plugin: Plugin;
+  /** The result from calling `init`. */
+  result: PluginResult;
+}
+
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Load plugin entries from the config file.
+ *
+ * Reads and parses the plugins config file. Returns an empty array if
+ * the file does not exist or contains no plugins.
+ *
+ * @param configPath - Path to the plugins config file (e.g. `~/.config/mini-coder/plugins.json`).
+ * @returns Array of {@link PluginEntry} records.
+ */
+export function loadPluginConfig(configPath: string): PluginEntry[] {
+  if (!existsSync(configPath)) return [];
+
+  const raw = readFileSync(configPath, "utf-8");
+  const parsed = JSON.parse(raw) as { plugins?: PluginEntry[] };
+  return parsed.plugins ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Plugin lifecycle
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and initialize all plugins from config entries.
+ *
+ * Imports each plugin module, calls its `init` with the agent context,
+ * and collects the results. Plugins that fail to load or initialize are
+ * skipped with a warning (logged via `onError`).
+ *
+ * @param entries - Plugin entries from the config file.
+ * @param context - The agent context to pass to each plugin.
+ * @param onError - Callback for plugin load/init errors.
+ * @returns Array of successfully loaded plugins.
+ */
+export async function initPlugins(
+  entries: PluginEntry[],
+  context: AgentContext,
+  onError?: (entry: PluginEntry, error: Error) => void,
+): Promise<LoadedPlugin[]> {
+  const loaded: LoadedPlugin[] = [];
+
+  for (const entry of entries) {
+    try {
+      const modulePath = resolve(entry.module);
+      const mod = (await import(modulePath)) as { default?: Plugin } & Plugin;
+      const plugin = mod.default ?? mod;
+
+      if (typeof plugin.init !== "function") {
+        throw new Error(
+          `Plugin "${entry.name}" does not export an init function`,
+        );
+      }
+
+      const result = await plugin.init(context, entry.config);
+      loaded.push({ entry, plugin, result });
+    } catch (err) {
+      onError?.(entry, err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  return loaded;
+}
+
+/**
+ * Destroy all loaded plugins.
+ *
+ * Calls `destroy` on each plugin that implements it. Errors during
+ * destruction are passed to `onError` — destruction continues for
+ * remaining plugins regardless.
+ *
+ * @param plugins - The loaded plugins to destroy.
+ * @param onError - Callback for destruction errors.
+ */
+export async function destroyPlugins(
+  plugins: LoadedPlugin[],
+  onError?: (entry: PluginEntry, error: Error) => void,
+): Promise<void> {
+  for (const { entry, plugin } of plugins) {
+    if (typeof plugin.destroy === "function") {
+      try {
+        await plugin.destroy();
+      } catch (err) {
+        onError?.(entry, err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,294 @@
+/**
+ * System prompt construction.
+ *
+ * Assembles the full system prompt from static base instructions and
+ * dynamic context: AGENTS.md files, skill catalog, plugin suffixes,
+ * and a session footer with date, CWD, and git state.
+ *
+ * @module
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import type { GitState } from "./git.ts";
+import { canonicalizePath } from "./paths.ts";
+import { buildSkillCatalog, type Skill } from "./skills.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A discovered AGENTS.md file with its content. */
+export interface AgentsMdFile {
+  /** Absolute path to the file. */
+  path: string;
+  /** Raw file content. */
+  content: string;
+}
+
+/** Options for building the system prompt. */
+interface BuildSystemPromptOpts {
+  /** Current working directory. */
+  cwd: string;
+  /** Current date string (YYYY-MM-DD). */
+  date: string;
+  /** Git repository state, or `null`/`undefined` if not in a repo. */
+  git?: GitState | null;
+  /** Discovered AGENTS.md files, ordered root-to-leaf. */
+  agentsMd?: AgentsMdFile[];
+  /** Discovered agent skills. */
+  skills?: Skill[];
+  /** Plugin system prompt suffixes. */
+  pluginSuffixes?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// AGENTS.md discovery
+// ---------------------------------------------------------------------------
+
+/** File name to look for during the AGENTS.md walk. */
+const AGENT_FILENAME = "AGENTS.md";
+
+/** Resolve the AGENTS.md scan root from git/home/env inputs. */
+export function resolveAgentsScanRoot(
+  _cwd: string,
+  gitRoot: string | null,
+  homeDir: string,
+  agentsRootEnv = process.env.MC_AGENTS_ROOT,
+): string {
+  if (gitRoot) {
+    return canonicalizePath(gitRoot);
+  }
+  if (agentsRootEnv === "/") {
+    return canonicalizePath("/");
+  }
+  return canonicalizePath(homeDir);
+}
+
+function isWithinScanRoot(path: string, scanRoot: string): boolean {
+  const relativePath = relative(scanRoot, path);
+  return (
+    relativePath === "" ||
+    (!relativePath.startsWith("..") && relativePath !== "..")
+  );
+}
+
+function collectAgentsSearchDirs(start: string, root: string): string[] {
+  if (!isWithinScanRoot(start, root)) {
+    return [start];
+  }
+
+  const dirs: string[] = [];
+  let current = start;
+  while (true) {
+    dirs.push(current);
+    if (current === root) {
+      return dirs.reverse();
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return dirs.reverse();
+    }
+    current = parent;
+  }
+}
+
+function readAgentsMdFile(dir: string): AgentsMdFile | null {
+  const filePath = join(dir, AGENT_FILENAME);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  return {
+    path: filePath,
+    content: readFileSync(filePath, "utf-8"),
+  };
+}
+
+/**
+ * Walk from `cwd` up to `scanRoot`, collecting AGENTS.md files.
+ *
+ * Also checks `globalAgentsDir` for global agent instructions when provided.
+ * Results are ordered root-to-leaf (general → specific), with global
+ * instructions first when present.
+ *
+ * @param cwd - Starting directory for the walk.
+ * @param scanRoot - Uppermost directory to include in the walk.
+ * @param globalAgentsDir - Optional directory for global agent instructions (e.g. `~/.agents/`).
+ * @returns Array of {@link AgentsMdFile} records, ordered general → specific.
+ */
+export function discoverAgentsMd(
+  cwd: string,
+  scanRoot: string,
+  globalAgentsDir?: string,
+): AgentsMdFile[] {
+  const root = canonicalizePath(scanRoot);
+  const start = canonicalizePath(cwd);
+  const files: AgentsMdFile[] = [];
+
+  if (globalAgentsDir) {
+    const globalFile = readAgentsMdFile(globalAgentsDir);
+    if (globalFile) {
+      files.push(globalFile);
+    }
+  }
+
+  for (const dir of collectAgentsSearchDirs(start, root)) {
+    const agentsFile = readAgentsMdFile(dir);
+    if (agentsFile) {
+      files.push(agentsFile);
+    }
+  }
+
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// Git line formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format a git state snapshot into a single-line string for the session footer.
+ *
+ * Fields are omitted when their values are zero. The git line format:
+ * `Git: branch main | 3 staged, 1 modified, 2 untracked | +5 −2 vs origin/main`
+ *
+ * @param state - The git state to format.
+ * @returns Formatted git status line.
+ */
+export function formatGitLine(state: GitState): string {
+  const parts: string[] = [`Git: branch ${state.branch}`];
+
+  // Working tree counts
+  const counts: string[] = [];
+  if (state.staged > 0) counts.push(`${state.staged} staged`);
+  if (state.modified > 0) counts.push(`${state.modified} modified`);
+  if (state.untracked > 0) counts.push(`${state.untracked} untracked`);
+  if (counts.length > 0) parts.push(counts.join(", "));
+
+  // Ahead/behind
+  if (state.ahead > 0 || state.behind > 0) {
+    const ab: string[] = [];
+    if (state.ahead > 0) ab.push(`+${state.ahead}`);
+    if (state.behind > 0) ab.push(`\u2212${state.behind}`);
+    parts.push(`${ab.join(" ")} vs origin/${state.branch}`);
+  }
+
+  return parts.join(" | ");
+}
+
+// ---------------------------------------------------------------------------
+// Base instructions
+// ---------------------------------------------------------------------------
+
+const BASE_INSTRUCTIONS = `You are mini-coder, a coding agent running in the user's terminal.
+
+# Role
+
+You are an autonomous, senior-level coding assistant. When the user gives a direction, proactively gather context, plan with the user, implement, and verify. Bias toward action: use planning first to clear any assumptions with the user, then implement the plan. Deliver working code, unless you are genuinely blocked.
+
+# Tools
+
+You have these core tools:
+
+- \`shell\` — run commands in the user's shell. Use this to explore the codebase (rg, find, ls, cat), run tests, build, git, and any other command. Prefer \`rg\` over \`grep\` for speed.
+- \`edit\` — make exact-text replacements in files. Provide the file path, the exact text to find, and the replacement text. The old text must match exactly one location in the file. To create a new file, use an empty old text and the full file content as new text.
+
+You may also have additional tools provided by plugins. Use them when they match the task.
+
+Workflow: **inspect with shell → mutate with edit → verify with shell**.
+
+# Code quality
+
+- Conform to the codebase's existing conventions: patterns, naming, formatting, language idioms.
+- Write correct, clear, minimal code. Don't over-engineer, don't add abstractions for hypothetical futures.
+- Reuse before creating. Search for existing helpers before writing new ones.
+- Tight error handling: no broad try/catch, no silent failures, no swallowed errors.
+- Keep type safety. Avoid \`any\` casts. Use proper types and guards.
+- Only add comments where the logic isn't self-evident.
+
+# Editing discipline
+
+- Read enough context before editing. Batch logical changes together rather than making many small edits.
+- Never revert changes you didn't make unless explicitly asked.
+- Never use destructive git commands (reset --hard, checkout --, clean -fd) unless the user requests it.
+- Default to ASCII. Only use non-ASCII characters when the file already uses them or there's clear justification.
+
+# Exploring the codebase
+
+- Think first: before any tool call, decide all files and information you need.
+- Batch reads: if you need multiple files, read them together in parallel rather than one at a time.
+- Only make sequential calls when a later call genuinely depends on an earlier result.
+
+# Communication
+
+- Be concise. Friendly coding teammate tone.
+- After making changes: lead with a quick explanation of what changed and why, then suggest logical next steps if any.
+- Don't dump large file contents you've written — reference file paths.
+- When suggesting multiple options, use numbered lists so the user can reply with a number.
+- If asked for a review, focus on bugs, risks, regressions, and missing tests. Findings first, ordered by severity.
+
+# Persistence
+
+- Carry work through to completion within the current turn. Don't stop at analysis or partial fixes.
+- If you encounter an error, diagnose and fix it rather than reporting it and stopping.
+- Avoid excessive looping: if you're re-reading or re-editing the same files without progress, stop and ask the user.`;
+
+// ---------------------------------------------------------------------------
+// System prompt assembly
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full system prompt.
+ *
+ * Assembly order:
+ * 1. Base instructions (static)
+ * 2. AGENTS.md content (project-specific)
+ * 3. Skills catalog (XML)
+ * 4. Plugin suffixes
+ * 5. Session footer (date, CWD, git)
+ *
+ * @param opts - Prompt construction options.
+ * @returns The assembled system prompt string.
+ */
+export function buildSystemPrompt(opts: BuildSystemPromptOpts): string {
+  const sections: string[] = [BASE_INSTRUCTIONS];
+
+  // 2. AGENTS.md content
+  if (opts.agentsMd && opts.agentsMd.length > 0) {
+    const agentsSection = [
+      "\n# Project Context\n",
+      "Project-specific instructions and guidelines:\n",
+    ];
+    for (const file of opts.agentsMd) {
+      agentsSection.push(`## ${file.path}\n`);
+      agentsSection.push(file.content);
+      agentsSection.push("");
+    }
+    sections.push(agentsSection.join("\n"));
+  }
+
+  // 3. Skills catalog
+  if (opts.skills && opts.skills.length > 0) {
+    const catalog = buildSkillCatalog(opts.skills);
+    if (catalog) sections.push(catalog);
+  }
+
+  // 4. Plugin suffixes
+  if (opts.pluginSuffixes) {
+    for (const suffix of opts.pluginSuffixes) {
+      sections.push(suffix);
+    }
+  }
+
+  // 5. Session footer
+  const footer: string[] = [];
+  footer.push(`Current date: ${opts.date}`);
+  footer.push(`Current working directory: ${opts.cwd}`);
+  if (opts.git) {
+    footer.push(formatGitLine(opts.git));
+  }
+  sections.push(footer.join("\n"));
+
+  return sections.join("\n");
+}