mini-coder 0.5.14 → 0.6.0

package/src/shared.ts

@@ -1,39 +1,118 @@
-/**
- * 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;
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseDocument } from "yaml";
+
+// Mixed bag of helpers that can be shared across the codebase
+
+export const DATA_DIR = join(homedir(), ".config", "mini-coder");
+export const SESSIONS_DIR = join(DATA_DIR, "sessions");
+export const AUTH_PATH = join(DATA_DIR, "auth.json");
+export const SETTINGS_PATH = join(DATA_DIR, "settings.json");
+
+export function secureRandomString(
+  length: number,
+  chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789",
+): string {
+  const result: string[] = [];
+  const charsLength = chars.length;
+  const maxValid = Math.floor(256 / charsLength) * charsLength;
+  const randomBytes = new Uint8Array(length * 2);
+
+  while (result.length < length) {
+    crypto.getRandomValues(randomBytes);
+
+    for (const byte of randomBytes) {
+      if (byte < maxValid) {
+        result.push(chars[byte % charsLength]);
+        if (result.length === length) break;
+      }
+    }
+  }
+
+  return result.join("");
+}
+
+export function elapsedTime(seconds: number): string {
+  if (seconds < 60) return `${seconds}s`;
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+
+  const days = Math.floor(hours / 24);
+  if (days < 7) return `${days}d`;
+
+  const weeks = Math.floor(days / 7);
+  if (weeks < 4) return `${weeks}w`;
+
+  const months = Math.floor(days / 30);
+  if (months < 12) return `${months}mo`;
+
+  const years = Math.floor(days / 365);
+  return `${years}y`;
+}
+
+export function relativeTime(timestamp: number): string {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  return elapsedTime(seconds);
+}
+
+export function onceEvery<T extends unknown[]>(
+  n: number,
+  fn: (...args: T) => void,
+) {
+  let calls = 0;
+
+  return (...args: T) => {
+    calls++;
+
+    if (calls % n === 0) {
+      fn(...args);
+    }
+  };
+}
+
+export function takeTail<T>(arr: T[], x: number): T[] {
+  return x <= 0 ? [] : arr.slice(-x);
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export function parseSkillFrontmatter(content: string) {
+  const match = /^---\s*\n([\s\S]*?)\n---/.exec(content);
+
+  if (!match) {
+    return undefined;
+  }
+
+  const doc = parseDocument(match[1]);
+  const data = doc.toJS() as unknown;
+
+  if (!data || typeof data !== "object") {
+    return undefined;
+  }
+
+  const record = data as Record<string, unknown>;
+  const name = typeof record.name === "string" ? record.name.trim() : "";
+  const description =
+    typeof record.description === "string" ? record.description.trim() : "";
+
+  if (!name || !description) {
+    return undefined;
+  }
+
+  return { name, description };
+}
+
+export function formatTimestamp(timestampMs: number): string {
+  return new Date(timestampMs).toLocaleTimeString("en-GB", {
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  });
 }

package/src/tool-bash.ts

@@ -0,0 +1,110 @@
+import { type Tool, Type } from "@mariozechner/pi-ai";
+import { secureRandomString } from "./shared";
+import type { ToolRunnerEvent } from "./types";
+
+const OUTPUT_THRESHOLD = 16000;
+const description = `## Bash CLI tool
+
+Execute shell commands on the user's environment.
+
+Best practices:
+
+- Use \`ls\` to list files.
+- Use \`fd\` or \`find\` to locate files/directories by name, type, size, time, permissions, etc.
+- Use \`rg\` or \`grep\` to search inside files for matching patterns.
+- Use \`cat -n\` or \`nl\` to read small files, or when you need the whole file.
+- Use \`sed -n\` with ranges to read sections of files. Prefer targeted reads. Avoid dumping very large (more than ~200 lines) files all at once.
+- Use \`cp\`, \`mv\`, and \`mkdir\` for file and directory operations, and \`rm\` to remove files and directories.
+- Use \`curl\` for web access. Use redirection to temp files for targeted reads.
+- Use development tools like \`git\`, \`gh\`, \`jq\`, etc, when appropriate.
+- Prefer \`cp -i\`, \`mv -i\`, \`rm -i\` when learning.
+- NEVER run destructive commands (\`rm -rf\`, \`git reset --hard\`, overwriting files) without confirming the target first.
+- Chain commands **only** when failure should stop the flow. Avoid long chains, **2 to 3 maximum**.
+- Avoid overly complex one-liners; readability matters.
+- Quote filenames: use \`"$file"\` not \`$file\`.
+- Be careful with spaces in filenames.
+
+Commands run in: ${process.cwd()}
+`;
+
+export const bash: Tool = {
+  name: "bash",
+  description,
+  parameters: Type.Object({
+    command: Type.String({
+      description:
+        "Shell command to execute. Prefer simple, focused commands over complex one-liners.",
+    }),
+  }),
+};
+
+export async function* runBashTool(
+  args: Record<string, any>,
+  signal?: AbortSignal,
+): AsyncGenerator<ToolRunnerEvent> {
+  // Redirect stderr into stdout for the whole shell session.
+  const proc = Bun.spawn(["bash", "-c", `exec 2>&1; ${args.command}`], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...Bun.env,
+      NO_COLOR: "1",
+    },
+    signal,
+  });
+
+  const decoder = new TextDecoder();
+  const reader = proc.stdout.getReader();
+
+  let output = "";
+  while (true) {
+    const { done, value } = await reader.read();
+
+    if (done) {
+      const remaining = Bun.stripANSI(decoder.decode());
+
+      if (remaining.length) {
+        output += remaining;
+        yield { type: "output", text: remaining };
+      }
+      break;
+    }
+
+    const text = Bun.stripANSI(decoder.decode(value, { stream: true }));
+
+    if (text.length) {
+      output += text;
+      yield { type: "output", text: text };
+    }
+  }
+
+  const exitCode = await proc.exited;
+
+  let result = `# EXIT CODE: ${exitCode}`;
+  if (output.length) {
+    result += `
+# OUTPUT:
+
+${output}`;
+  }
+
+  // If `out` is too big, more than ~XXKB, write it to a temp file
+  // And add that to the truncation label for the agent to be able
+  // to continue the read with scans. This is to protect context,
+  // not a general read guard. The hint is for the agent, not the TUI
+  if (result.length > OUTPUT_THRESHOLD) {
+    const key = `${Date.now()}-${secureRandomString(4)}`;
+    const pathname = `/tmp/bash_result_${key}.txt`;
+    await Bun.write(pathname, result);
+    result = `${result.substring(0, OUTPUT_THRESHOLD)}
+
+Truncated at ~${OUTPUT_THRESHOLD / 1000}KB. Full output at ${pathname}`;
+  }
+
+  yield {
+    type: "result",
+    text: result,
+  };
+
+  return result;
+}

package/src/tool-edit.ts

@@ -0,0 +1,133 @@
+import { isAbsolute, join } from "node:path";
+import { type Tool, Type } from "@mariozechner/pi-ai";
+import { createPatch } from "diff";
+import type { ToolRunnerEvent } from "./types";
+
+const description = `## Edit tool
+
+A find-and-replace file editor. Use it to create new files or modify existing ones safely. Always prefer this tool over bash editing methods (sed, awk, etc).
+
+### Rules
+- The tool refuses to edit on multiple matches of \`oldText\`. Be specific with your matching text.
+- Prefer patch-based edits (small targeted replacements) for multi-line or semantic changes.
+- Do NOT reproduce entire files. Use shell file operations (\`cp\`, \`mv\`, etc) for wholesale file replacement instead.
+
+### Failure modes
+- If \`oldText\` is not found, the edit fails. Verify the exact text first.
+- If \`oldText\` matches multiple locations, the edit fails. Narrow your match and retry.
+- If the file does not exist and \`oldText\` is non-empty, the edit fails.
+
+<example>
+Edit a single line:
+path: src/utils.ts
+oldText: const MAX_RETRIES = 3;
+newText: const MAX_RETRIES = 5;
+</example>
+
+<example>
+Patch-based edit (preferred for multi-line changes):
+path: src/utils.ts
+oldText: function oldHelper() {\n  return 1;\n}
+newText: function newHelper() {\n  return 2;\n}\n\nfunction oldHelper() {\n  return 1;\n}
+</example>
+`;
+
+export const edit: Tool = {
+  name: `edit`,
+  description,
+  parameters: Type.Object({
+    path: Type.String({
+      description:
+        "File path. Absolute or relative to the current working directory.",
+    }),
+    oldText: Type.String({
+      description:
+        'Exact text to find and replace. Empty string means "create new file".',
+    }),
+    newText: Type.String({
+      description: "Replacement text (or full content for new files)",
+    }),
+  }),
+};
+
+function findAllIndexes(text: string, sub: string): number[] {
+  if (sub.length === 0) return [];
+
+  const indexes: number[] = [];
+
+  let pos = text.indexOf(sub, 0);
+  while (pos !== -1) {
+    indexes.push(pos);
+    pos += sub.length; // use pos += 1 if you want overlapping matches
+    pos = text.indexOf(sub, pos);
+  }
+
+  return indexes;
+}
+
+export async function* runEditTool(
+  args: Record<string, any>,
+  signal?: AbortSignal,
+): AsyncGenerator<ToolRunnerEvent> {
+  const filePath = isAbsolute(args.path)
+    ? args.path
+    : join(process.cwd(), args.path);
+  const file = Bun.file(filePath);
+  const exists = await file.exists();
+
+  if (args.oldText === "") {
+    if (exists) {
+      yield { type: "result", text: `File already exists: ${filePath}` };
+      return;
+    }
+
+    await Bun.write(file, args.newText);
+    yield {
+      type: "result",
+      text: `File written: ${filePath}\n\n${args.newText}`,
+    };
+    return;
+  }
+
+  if (!exists) {
+    yield { type: "result", text: `File not found: ${filePath}` };
+    return;
+  }
+
+  const content = await file.text();
+  const matches = findAllIndexes(content, args.oldText);
+
+  if (matches.length === 0) {
+    yield { type: "result", text: `Old text not found in: ${filePath}` };
+    return;
+  }
+
+  if (matches.length > 1) {
+    yield {
+      type: "result",
+      text: `Multiple matches found in ${filePath}: ${matches.length} matches, be more specific and try again`,
+    };
+    return;
+  }
+
+  const idx = matches[0];
+  const updated =
+    content.slice(0, idx) +
+    args.newText +
+    content.slice(idx + args.oldText.length);
+
+  if (signal?.aborted) {
+    yield { type: "result", text: "Aborted before write." };
+    return;
+  }
+
+  await file.write(updated);
+  const patch = createPatch(filePath, content, updated);
+
+  yield {
+    type: "result",
+    text: `File edited: ${filePath}\n\n${patch}`,
+  };
+
+  return;
+}

package/src/tool-task.ts

@@ -0,0 +1,114 @@
+import { type Message, type Tool, Type } from "@mariozechner/pi-ai";
+import { streamAgent } from "./agent";
+import { buildSystemPrompt, TASK_PROMPT } from "./prompt";
+import { estimateTokens, formatTimestamp } from "./shared";
+import { bash, runBashTool } from "./tool-bash";
+import { edit, runEditTool } from "./tool-edit";
+import type {
+  AgentContex,
+  CliOptions,
+  ToolAndRunner,
+  ToolRunnerEvent,
+} from "./types";
+
+const description = `## Task tool
+
+Use this tool for multi-step work that would otherwise require multiple individual tool calls. The tool executes a detailed plan and returns results.
+
+Best practices:
+
+- For exploration (codebase, filesystem, web), specify exactly what you are looking for and the expected output format. For example: "Find all files relevant to tests. Return the exact paths and a description of each file."
+- For edits, specify exact diffs and the target file for each change.
+- For anything else, provide a specific, detailed set of instructions and your expected results.
+`;
+
+export const task: Tool = {
+  name: "task",
+  description,
+  parameters: Type.Object({
+    prompt: Type.String({
+      description:
+        "Detailed description of the work to perform. Be specific about expected outputs and any constraints.",
+    }),
+  }),
+};
+
+export async function* runTaskTool(
+  options: CliOptions,
+  args: Record<string, any>,
+  signal?: AbortSignal,
+): AsyncGenerator<ToolRunnerEvent> {
+  const tools: ToolAndRunner[] = [
+    { tool: bash, runner: runBashTool },
+    { tool: edit, runner: runEditTool },
+  ];
+  const messages: Message[] = [
+    { role: "user", content: args.prompt || "", timestamp: Date.now() },
+  ];
+
+  const systemPrompt = await buildSystemPrompt(TASK_PROMPT);
+  const ctx: AgentContex = {
+    systemPrompt,
+    tools,
+    messages,
+    options,
+    signal,
+  };
+
+  let output = "";
+  const agent = streamAgent(ctx);
+  for await (const ev of agent) {
+    switch (ev.type) {
+      case "message_start": {
+        const text = `[${formatTimestamp(ev.partial.timestamp)}] Working...`;
+        output += text;
+        yield { type: "output", text };
+        break;
+      }
+      case "message_end": {
+        const thinking = ev.message.content
+          .filter((b) => b.type === "thinking")
+          .map((b) => b.thinking)
+          .join("");
+        const messageText = ev.message.content
+          .filter((b) => b.type === "text")
+          .map((b) => b.text)
+          .join("");
+        const calls = ev.message.content
+          .filter((b) => b.type === "toolCall")
+          .map((b) => b.name);
+
+        let text = `[${formatTimestamp(ev.message.timestamp)}]`;
+        if (thinking.length > 0) {
+          const thinkingTokens = estimateTokens(thinking);
+          text += `Thinking... (${thinkingTokens} tokens)`;
+        }
+        if (messageText.length > 0) {
+          text += `\n\n${messageText}\n`;
+        }
+        if (calls.length > 0) {
+          text += ` \nTool calls:`;
+          for (const c of calls) {
+            text += `\n${c}`;
+          }
+        }
+
+        output += text;
+        yield { type: "output", text };
+        break;
+      }
+      case "tool_message_end": {
+        const ts = formatTimestamp(ev.message.timestamp);
+        const name = ev.message.toolName;
+        const symbol = !ev.message.isError ? "✓ " : "✗ ";
+        const text = `[${ts}] ${name} ${symbol}`;
+
+        output += text;
+        yield { type: "output", text };
+        break;
+      }
+    }
+  }
+
+  yield { type: "result", text: output };
+}

package/src/tui-components.ts

@@ -0,0 +1,150 @@
+import { type Color, HStack, Text } from "@cel-tui/core";
+import { onceEvery } from "./shared";
+import type { TUIState } from "./types";
+
+export const theme = {
+  black: "color00" as Color,
+  bblack: "color08" as Color,
+
+  red: "color01" as Color,
+  bred: "color09" as Color,
+
+  green: "color02" as Color,
+  bgreen: "color10" as Color,
+
+  yellow: "color03" as Color,
+  byellow: "color11" as Color,
+
+  blue: "color04" as Color,
+  bblue: "color12" as Color,
+
+  magenta: "color05" as Color,
+  bmagenta: "color13" as Color,
+
+  cyan: "color06" as Color,
+  bcyan: "color14" as Color,
+
+  white: "color07" as Color,
+  bwhite: "color15" as Color,
+};
+
+export function TextPill(
+  content: string,
+  fgColor: Color,
+  bgColor: Color,
+  size?: number | undefined,
+) {
+  return HStack({ gap: 1, width: size }, [
+    HStack({ bgColor, padding: { x: 1 } }, [
+      Text(content, { bold: true, fgColor }),
+    ]),
+  ]);
+}
+
+export function Spinner() {
+  const spinnerFrames = [
+    "⠁",
+    "⠂",
+    "⠄",
+    "⡀",
+    "⡈",
+    "⡐",
+    "⡠",
+    "⣀",
+    "⣁",
+    "⣂",
+    "⣄",
+    "⣌",
+    "⣔",
+    "⣤",
+    "⣥",
+    "⣦",
+    "⣮",
+    "⣶",
+    "⣷",
+    "⣿",
+    "⡿",
+    "⠿",
+    "⢟",
+    "⠟",
+    "⡛",
+    "⠛",
+    "⠫",
+    "⢋",
+    "⠋",
+    "⠍",
+    "⡉",
+    "⠉",
+    "⠑",
+    "⠡",
+    "⢁",
+  ];
+  let spinnerTick = 0;
+  const spinnerEvery = onceEvery(4, () => spinnerTick++);
+  const currentSpinner = () =>
+    spinnerFrames[spinnerTick % spinnerFrames.length];
+
+  return { spinnerEvery, currentSpinner };
+}
+
+export function ActivityPill(state: TUIState, spinnerFrame: string) {
+  let label = "idle";
+  const frame = state.streaming ? spinnerFrame : "";
+
+  if (frame) {
+    label = frame;
+  }
+
+  return Text(label);
+}
+
+export function ContextPill(state: TUIState) {
+  let text = "";
+  let bg = theme.bgreen;
+  if (!state.contextSize) {
+    text = "0%";
+    bg = theme.bwhite;
+  } else {
+    // Colors show the progress in the "smart window" or how much
+    // before the dumb zone. The user facing percentage is the model
+    // amount. An elegant way to show both :)
+    const max = state.options.model.contextWindow;
+    const smartMax = 80000;
+    const percent = Math.floor((state.contextSize / max) * 100);
+    const smartPercent = Math.floor((state.contextSize / smartMax) * 100);
+    if (smartPercent > 90) {
+      bg = theme.bred;
+    } else if (smartPercent > 80) {
+      bg = theme.red;
+    } else if (smartPercent > 70) {
+      bg = theme.yellow;
+    } else if (smartPercent > 50) {
+      bg = theme.byellow;
+    }
+    text = `~${percent}%`;
+  }
+
+  text += ` (${state.options.model.contextWindow / 1000}k)`;
+
+  return TextPill(text, theme.bblack, bg);
+}
+
+export function GitPill(state: TUIState) {
+  return TextPill(state.gitBranch ?? "No git.", theme.bwhite, theme.bblack);
+}
+
+export function ModelPill(state: TUIState) {
+  // Like loot: Gold/purple/blue/green/white -> xhigh/high/medium/low/minimal
+  switch (state.options.effort) {
+    case "xhigh":
+      return TextPill(state.options.model.name, theme.white, theme.yellow);
+    case "high":
+      return TextPill(state.options.model.name, theme.white, theme.magenta);
+    case "medium":
+      return TextPill(state.options.model.name, theme.white, theme.blue);
+    case "low":
+      return TextPill(state.options.model.name, theme.white, theme.green);
+  }
+  // Minimal
+  return TextPill(state.options.model.name, theme.bwhite, theme.bblack);
+}