micode 0.6.0 → 0.7.1

package/src/tools/look-at.ts

@@ -0,0 +1,210 @@
+import { tool } from "@opencode-ai/plugin/tool";
+import { readFileSync, statSync } from "node:fs";
+import { extname, basename } from "node:path";
+
+// File size threshold for triggering extraction (100KB)
+const LARGE_FILE_THRESHOLD = 100 * 1024;
+
+// Max lines to return without extraction
+const MAX_LINES_WITHOUT_EXTRACT = 200;
+
+// Supported file types for smart extraction
+const EXTRACTABLE_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".py",
+  ".go",
+  ".rs",
+  ".java",
+  ".md",
+  ".json",
+  ".yaml",
+  ".yml",
+];
+
+function extractStructure(content: string, ext: string): string {
+  const lines = content.split("\n");
+
+  switch (ext) {
+    case ".ts":
+    case ".tsx":
+    case ".js":
+    case ".jsx":
+      return extractTypeScriptStructure(lines);
+    case ".py":
+      return extractPythonStructure(lines);
+    case ".go":
+      return extractGoStructure(lines);
+    case ".md":
+      return extractMarkdownStructure(lines);
+    case ".json":
+      return extractJsonStructure(content);
+    case ".yaml":
+    case ".yml":
+      return extractYamlStructure(lines);
+    default:
+      return extractGenericStructure(lines);
+  }
+}
+
+function extractTypeScriptStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture exports, classes, interfaces, types, functions
+    if (
+      trimmed.startsWith("export ") ||
+      trimmed.startsWith("class ") ||
+      trimmed.startsWith("interface ") ||
+      trimmed.startsWith("type ") ||
+      trimmed.startsWith("function ") ||
+      trimmed.startsWith("const ") ||
+      trimmed.startsWith("async function ")
+    ) {
+      // Get the signature (first line only for multi-line)
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractPythonStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture classes, functions, decorators
+    if (
+      trimmed.startsWith("class ") ||
+      trimmed.startsWith("def ") ||
+      trimmed.startsWith("async def ") ||
+      trimmed.startsWith("@")
+    ) {
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractGoStructure(lines: string[]): string {
+  const output: string[] = ["## Structure\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Capture types, functions, methods
+    if (trimmed.startsWith("type ") || trimmed.startsWith("func ") || trimmed.startsWith("package ")) {
+      const signature = trimmed.length > 80 ? `${trimmed.slice(0, 80)}...` : trimmed;
+      output.push(`Line ${i + 1}: ${signature}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractMarkdownStructure(lines: string[]): string {
+  const output: string[] = ["## Outline\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Capture headings
+    if (line.startsWith("#")) {
+      output.push(`Line ${i + 1}: ${line}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractJsonStructure(content: string): string {
+  try {
+    const obj = JSON.parse(content);
+    const keys = Object.keys(obj);
+    return `## Top-level keys (${keys.length})\n\n${keys.slice(0, 50).join(", ")}${keys.length > 50 ? "..." : ""}`;
+  } catch {
+    return "## Invalid JSON";
+  }
+}
+
+function extractYamlStructure(lines: string[]): string {
+  const output: string[] = ["## Top-level keys\n"];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Top-level keys (no indentation)
+    if (line.match(/^[a-zA-Z_][a-zA-Z0-9_]*:/)) {
+      output.push(`Line ${i + 1}: ${line}`);
+    }
+  }
+
+  return output.join("\n");
+}
+
+function extractGenericStructure(lines: string[]): string {
+  // For unknown files, just show first/last lines and line count
+  const total = lines.length;
+  const preview = lines.slice(0, 10).join("\n");
+  const tail = lines.slice(-5).join("\n");
+
+  return `## File Preview (${total} lines)\n\n### First 10 lines:\n${preview}\n\n### Last 5 lines:\n${tail}`;
+}
+
+export const look_at = tool({
+  description: `Extract key information from a file to save context tokens.
+For large files, returns structure/outline instead of full content.
+Use when you need to understand a file without loading all content.
+Ideal for: large files, getting file structure, quick overview.`,
+  args: {
+    filePath: tool.schema.string().describe("Path to the file"),
+    extract: tool.schema
+      .string()
+      .optional()
+      .describe("What to extract: 'structure', 'imports', 'exports', 'all' (default: auto)"),
+  },
+  execute: async (args) => {
+    try {
+      const stats = statSync(args.filePath);
+      const ext = extname(args.filePath).toLowerCase();
+      const name = basename(args.filePath);
+
+      // Read file
+      const content = readFileSync(args.filePath, "utf-8");
+      const lines = content.split("\n");
+
+      // For small files, return full content
+      if (stats.size < LARGE_FILE_THRESHOLD && lines.length <= MAX_LINES_WITHOUT_EXTRACT) {
+        return `## ${name} (${lines.length} lines)\n\n${content}`;
+      }
+
+      // For large files, extract structure
+      let output = `## ${name}\n`;
+      output += `**Size**: ${Math.round(stats.size / 1024)}KB | **Lines**: ${lines.length}\n\n`;
+
+      if (EXTRACTABLE_EXTENSIONS.includes(ext)) {
+        output += extractStructure(content, ext);
+      } else {
+        output += extractGenericStructure(lines);
+      }
+
+      output += `\n\n---\n*Use Read tool with line offset/limit for specific sections*`;
+
+      return output;
+    } catch (e) {
+      return `Error: ${e instanceof Error ? e.message : String(e)}`;
+    }
+  },
+});

package/src/tools/pty/buffer.ts

@@ -0,0 +1,49 @@
+// src/tools/pty/buffer.ts
+import type { SearchMatch } from "./types";
+
+const parsed = parseInt(process.env.PTY_MAX_BUFFER_LINES || "50000", 10);
+const DEFAULT_MAX_LINES = isNaN(parsed) ? 50000 : parsed;
+
+export class RingBuffer {
+  private lines: string[] = [];
+  private maxLines: number;
+
+  constructor(maxLines: number = DEFAULT_MAX_LINES) {
+    this.maxLines = maxLines;
+  }
+
+  append(data: string): void {
+    const newLines = data.split("\n");
+    for (const line of newLines) {
+      this.lines.push(line);
+      if (this.lines.length > this.maxLines) {
+        this.lines.shift();
+      }
+    }
+  }
+
+  read(offset: number = 0, limit?: number): string[] {
+    const start = Math.max(0, offset);
+    const end = limit !== undefined ? start + limit : this.lines.length;
+    return this.lines.slice(start, end);
+  }
+
+  search(pattern: RegExp): SearchMatch[] {
+    const matches: SearchMatch[] = [];
+    for (let i = 0; i < this.lines.length; i++) {
+      const line = this.lines[i];
+      if (line !== undefined && pattern.test(line)) {
+        matches.push({ lineNumber: i + 1, text: line });
+      }
+    }
+    return matches;
+  }
+
+  get length(): number {
+    return this.lines.length;
+  }
+
+  clear(): void {
+    this.lines = [];
+  }
+}

package/src/tools/pty/index.ts

@@ -0,0 +1,34 @@
+// src/tools/pty/index.ts
+export { PTYManager } from "./manager";
+export { RingBuffer } from "./buffer";
+export { createPtySpawnTool } from "./tools/spawn";
+export { createPtyWriteTool } from "./tools/write";
+export { createPtyReadTool } from "./tools/read";
+export { createPtyListTool } from "./tools/list";
+export { createPtyKillTool } from "./tools/kill";
+export type {
+  PTYSession,
+  PTYSessionInfo,
+  PTYStatus,
+  SpawnOptions,
+  ReadResult,
+  SearchMatch,
+  SearchResult,
+} from "./types";
+
+import type { PTYManager } from "./manager";
+import { createPtySpawnTool } from "./tools/spawn";
+import { createPtyWriteTool } from "./tools/write";
+import { createPtyReadTool } from "./tools/read";
+import { createPtyListTool } from "./tools/list";
+import { createPtyKillTool } from "./tools/kill";
+
+export function createPtyTools(manager: PTYManager) {
+  return {
+    pty_spawn: createPtySpawnTool(manager),
+    pty_write: createPtyWriteTool(manager),
+    pty_read: createPtyReadTool(manager),
+    pty_list: createPtyListTool(manager),
+    pty_kill: createPtyKillTool(manager),
+  };
+}

package/src/tools/pty/manager.ts

@@ -0,0 +1,159 @@
+// src/tools/pty/manager.ts
+import { spawn, type IPty } from "bun-pty";
+import { RingBuffer } from "./buffer";
+import type { PTYSession, PTYSessionInfo, SpawnOptions, ReadResult, SearchResult } from "./types";
+
+function generateId(): string {
+  const hex = Array.from(crypto.getRandomValues(new Uint8Array(4)))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+  return `pty_${hex}`;
+}
+
+export class PTYManager {
+  private sessions: Map<string, PTYSession> = new Map();
+
+  spawn(opts: SpawnOptions): PTYSessionInfo {
+    const id = generateId();
+    const args = opts.args ?? [];
+    const workdir = opts.workdir ?? process.cwd();
+    const env = { ...process.env, ...opts.env } as Record<string, string>;
+    const title = opts.title ?? (`${opts.command} ${args.join(" ")}`.trim() || `Terminal ${id.slice(-4)}`);
+
+    const ptyProcess: IPty = spawn(opts.command, args, {
+      name: "xterm-256color",
+      cols: 120,
+      rows: 40,
+      cwd: workdir,
+      env,
+    });
+
+    const buffer = new RingBuffer();
+    const session: PTYSession = {
+      id,
+      title,
+      command: opts.command,
+      args,
+      workdir,
+      env: opts.env,
+      status: "running",
+      pid: ptyProcess.pid,
+      createdAt: new Date(),
+      parentSessionId: opts.parentSessionId,
+      buffer,
+      process: ptyProcess,
+    };
+
+    this.sessions.set(id, session);
+
+    ptyProcess.onData((data: string) => {
+      buffer.append(data);
+    });
+
+    ptyProcess.onExit(({ exitCode }: { exitCode: number }) => {
+      if (session.status === "running") {
+        session.status = "exited";
+        session.exitCode = exitCode;
+      }
+    });
+
+    return this.toInfo(session);
+  }
+
+  write(id: string, data: string): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+    if (session.status !== "running") {
+      return false;
+    }
+    session.process.write(data);
+    return true;
+  }
+
+  read(id: string, offset: number = 0, limit?: number): ReadResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const lines = session.buffer.read(offset, limit);
+    const totalLines = session.buffer.length;
+    const hasMore = offset + lines.length < totalLines;
+    return { lines, totalLines, offset, hasMore };
+  }
+
+  search(id: string, pattern: RegExp, offset: number = 0, limit?: number): SearchResult | null {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return null;
+    }
+    const allMatches = session.buffer.search(pattern);
+    const totalMatches = allMatches.length;
+    const totalLines = session.buffer.length;
+    const paginatedMatches = limit !== undefined ? allMatches.slice(offset, offset + limit) : allMatches.slice(offset);
+    const hasMore = offset + paginatedMatches.length < totalMatches;
+    return { matches: paginatedMatches, totalMatches, totalLines, offset, hasMore };
+  }
+
+  list(): PTYSessionInfo[] {
+    return Array.from(this.sessions.values()).map((s) => this.toInfo(s));
+  }
+
+  get(id: string): PTYSessionInfo | null {
+    const session = this.sessions.get(id);
+    return session ? this.toInfo(session) : null;
+  }
+
+  kill(id: string, cleanup: boolean = false): boolean {
+    const session = this.sessions.get(id);
+    if (!session) {
+      return false;
+    }
+
+    if (session.status === "running") {
+      try {
+        session.process.kill();
+      } catch {
+        // Process may already be dead
+      }
+      session.status = "killed";
+    }
+
+    if (cleanup) {
+      session.buffer.clear();
+      this.sessions.delete(id);
+    }
+
+    return true;
+  }
+
+  cleanupBySession(parentSessionId: string): void {
+    for (const [id, session] of this.sessions) {
+      if (session.parentSessionId === parentSessionId) {
+        this.kill(id, true);
+      }
+    }
+  }
+
+  cleanupAll(): void {
+    for (const id of this.sessions.keys()) {
+      this.kill(id, true);
+    }
+  }
+
+  private toInfo(session: PTYSession): PTYSessionInfo {
+    return {
+      id: session.id,
+      title: session.title,
+      command: session.command,
+      args: session.args,
+      workdir: session.workdir,
+      status: session.status,
+      exitCode: session.exitCode,
+      pid: session.pid,
+      createdAt: session.createdAt,
+      lineCount: session.buffer.length,
+    };
+  }
+}

package/src/tools/pty/tools/kill.ts

@@ -0,0 +1,68 @@
+// src/tools/pty/tools/kill.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Terminates a PTY session and optionally cleans up its buffer.
+
+Use this tool to:
+- Stop a running process (sends SIGTERM)
+- Clean up an exited session to free memory
+- Remove a session from the list
+
+Usage:
+- \`id\`: The PTY session ID (from pty_spawn or pty_list)
+- \`cleanup\`: If true, removes the session and frees the buffer (default: false)
+
+Behavior:
+- If the session is running, it will be killed (status becomes "killed")
+- If cleanup=false (default), the session remains in the list with its output buffer intact
+- If cleanup=true, the session is removed entirely and the buffer is freed
+- Keeping sessions without cleanup allows you to compare logs between runs
+
+Tips:
+- Use cleanup=false if you might want to read the output later
+- Use cleanup=true when you're done with the session entirely
+- To send Ctrl+C instead of killing, use pty_write with data="\\x03"
+
+Examples:
+- Kill but keep logs: cleanup=false (or omit)
+- Kill and remove: cleanup=true`;
+
+export function createPtyKillTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {
+      id: tool.schema.string().describe("The PTY session ID (e.g., pty_a1b2c3d4)"),
+      cleanup: tool.schema
+        .boolean()
+        .optional()
+        .describe("If true, removes the session and frees the buffer (default: false)"),
+    },
+    execute: async (args) => {
+      const session = manager.get(args.id);
+      if (!session) {
+        throw new Error(`PTY session '${args.id}' not found. Use pty_list to see active sessions.`);
+      }
+
+      const wasRunning = session.status === "running";
+      const cleanup = args.cleanup ?? false;
+      const success = manager.kill(args.id, cleanup);
+
+      if (!success) {
+        throw new Error(`Failed to kill PTY session '${args.id}'.`);
+      }
+
+      const action = wasRunning ? "Killed" : "Cleaned up";
+      const cleanupNote = cleanup ? " (session removed)" : " (session retained for log access)";
+
+      return [
+        `<pty_killed>`,
+        `${action}: ${args.id}${cleanupNote}`,
+        `Title: ${session.title}`,
+        `Command: ${session.command} ${session.args.join(" ")}`,
+        `Final line count: ${session.lineCount}`,
+        `</pty_killed>`,
+      ].join("\n");
+    },
+  });
+}

package/src/tools/pty/tools/list.ts

@@ -0,0 +1,55 @@
+// src/tools/pty/tools/list.ts
+import { tool } from "@opencode-ai/plugin/tool";
+import type { PTYManager } from "../manager";
+
+const DESCRIPTION = `Lists all PTY sessions (active and exited).
+
+Use this tool to:
+- See all running and exited PTY sessions
+- Get session IDs for use with other pty_* tools
+- Check the status and output line count of each session
+- Monitor which processes are still running
+
+Returns for each session:
+- \`id\`: Unique identifier for use with other tools
+- \`title\`: Human-readable name
+- \`command\`: The command that was executed
+- \`status\`: Current status (running, exited, killed)
+- \`exitCode\`: Exit code (if exited/killed)
+- \`pid\`: Process ID
+- \`lineCount\`: Number of lines in the output buffer
+- \`createdAt\`: When the session was created
+
+Tips:
+- Use the session ID with pty_read, pty_write, or pty_kill
+- Sessions remain in the list after exit until explicitly cleaned up with pty_kill
+- This allows you to compare output from multiple sessions`;
+
+export function createPtyListTool(manager: PTYManager) {
+  return tool({
+    description: DESCRIPTION,
+    args: {},
+    execute: async () => {
+      const sessions = manager.list();
+
+      if (sessions.length === 0) {
+        return "<pty_list>\nNo active PTY sessions.\n</pty_list>";
+      }
+
+      const lines = ["<pty_list>"];
+      for (const session of sessions) {
+        const exitInfo = session.exitCode !== undefined ? ` (exit: ${session.exitCode})` : "";
+        lines.push(`[${session.id}] ${session.title}`);
+        lines.push(`  Command: ${session.command} ${session.args.join(" ")}`);
+        lines.push(`  Status: ${session.status}${exitInfo}`);
+        lines.push(`  PID: ${session.pid} | Lines: ${session.lineCount} | Workdir: ${session.workdir}`);
+        lines.push(`  Created: ${session.createdAt.toISOString()}`);
+        lines.push("");
+      }
+      lines.push(`Total: ${sessions.length} session(s)`);
+      lines.push("</pty_list>");
+
+      return lines.join("\n");
+    },
+  });
+}