opencode-debug-agent 0.1.0 → 0.1.2

package/dist/index.js

@@ -10,9 +10,6 @@ var __export = (target, all) => {
     });
 };
 
-// src/index.ts
-import path from "path";
-
 // node_modules/zod/v4/classic/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -13970,7 +13967,7 @@ class DebugServer {
         };
         await this.appendLog(entry);
         return c.json({ success: true });
-      } catch (error45) {
+      } catch {
         return c.json({ error: "Invalid JSON" }, 400);
       }
     });
@@ -14176,60 +14173,124 @@ var debugStatus = tool({
 });
 
 // src/index.ts
-function parseSkillFrontmatter(content) {
-  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-  const match2 = content.match(frontmatterRegex);
-  if (!match2) {
-    return { frontmatter: { name: "", description: "" }, body: content.trim() };
-  }
-  const [, yamlContent, body] = match2;
-  const frontmatter = { name: "", description: "" };
-  for (const line of yamlContent.split(`
-`)) {
-    const colonIndex = line.indexOf(":");
-    if (colonIndex === -1)
-      continue;
-    const key = line.slice(0, colonIndex).trim();
-    const value = line.slice(colonIndex + 1).trim();
-    if (key === "name")
-      frontmatter.name = value;
-    if (key === "description")
-      frontmatter.description = value;
-  }
-  return { frontmatter, body: body.trim() };
-}
-async function loadSkills() {
-  const skills = [];
-  const skillDir = path.join(import.meta.dir, "skill");
-  const glob = new Bun.Glob("**/SKILL.md");
-  try {
-    for await (const file2 of glob.scan({ cwd: skillDir, absolute: true })) {
-      const content = await Bun.file(file2).text();
-      const { frontmatter, body } = parseSkillFrontmatter(content);
-      if (frontmatter.name) {
-        skills.push({
-          name: frontmatter.name,
-          description: frontmatter.description,
-          content: body
-        });
-      }
-    }
-  } catch {}
-  return skills;
-}
-async function loadAgentPrompt() {
-  try {
-    const agentFile = path.join(import.meta.dir, "agent", "debug.md");
-    const content = await Bun.file(agentFile).text();
-    const match2 = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-    return match2 ? match2[1].trim() : content;
-  } catch {
-    return "You are a debugging specialist.";
-  }
-}
-var DebugAgentPlugin = async () => {
-  const skills = await loadSkills();
-  const agentPrompt = await loadAgentPrompt();
+var AGENT_PROMPT = `You are a debugging specialist. Your purpose is to help users debug runtime issues by capturing and analyzing execution data.
+
+## IMPORTANT: Port Handling
+- \`debug_start\` returns a ready-to-use \`snippet\` with the correct port baked in
+- ALWAYS use the snippet from the tool response - never hardcode ports
+- If you need the current port later, call \`debug_status\`
+- The server remembers its port across sessions, so existing instrumentations keep working
+
+## Workflow
+
+1. Call \`debug_start\` to start the debug server
+2. Use the returned \`snippet\` to insert fetch() calls at strategic locations in the user's code
+   - Replace \`LABEL_HERE\` with a descriptive label (e.g., "before-api-call", "user-input", "loop-iteration")
+   - Replace \`YOUR_DATA\` with the variables you want to capture
+3. Ask user to reproduce the issue
+4. Call \`debug_read\` to analyze captured logs
+5. Identify the problem from the runtime data
+6. Call \`debug_stop\` when done
+7. Remove all fetch() instrumentation calls from the code
+
+## If Instrumentations Already Exist
+- Call \`debug_status\` first to check for existing port
+- Use \`grep\` to find existing \`localhost:\\d+/log\` patterns in codebase
+- Start server on the same port to avoid breaking existing instrumentations
+
+## Example Instrumentation
+
+After calling \`debug_start\`, you'll get a snippet like:
+\`\`\`javascript
+fetch("http://localhost:54321/log", {
+  method: "POST",
+  headers: {"Content-Type": "application/json"},
+  body: JSON.stringify({label: "LABEL_HERE", data: {YOUR_DATA}})
+})
+\`\`\`
+
+Insert this at strategic points:
+\`\`\`javascript
+// Before an API call
+fetch("http://localhost:54321/log", {
+  method: "POST",
+  headers: {"Content-Type": "application/json"},
+  body: JSON.stringify({label: "pre-api", data: {userId, requestBody}})
+})
+
+// After receiving response
+fetch("http://localhost:54321/log", {
+  method: "POST",
+  headers: {"Content-Type": "application/json"},
+  body: JSON.stringify({label: "post-api", data: {response, status}})
+})
+\`\`\`
+
+## Tips
+- Use descriptive labels to make logs easy to understand
+- Capture relevant variables at each point
+- Add instrumentation around suspected problem areas
+- Compare expected vs actual values in the logs`;
+var DEBUG_SKILL = {
+  name: "debug",
+  description: "Runtime debugging - start a debug server, instrument code with fetch() calls, capture and analyze execution data",
+  content: `## CRITICAL: Port Handling
+- \`debug_start\` returns a \`snippet\` with the correct port - ALWAYS use it
+- Never hardcode ports in fetch() calls
+- Call \`debug_status\` to get current port if needed later
+- Server persists port to \`.opencode/debug.port\` so existing instrumentations keep working
+
+## Workflow
+
+1. \`debug_start\` - Returns {port, url, snippet}
+2. Insert the returned \`snippet\` at strategic code locations:
+   - Replace \`LABEL_HERE\` with descriptive label (e.g., "before-api", "after-parse")
+   - Replace \`YOUR_DATA\` with variables to capture (e.g., \`{userId, response}\`)
+3. Ask user to reproduce the issue
+4. \`debug_read\` - Analyze captured logs (returns parsed JSON array)
+5. \`debug_stop\` - Stop server when done
+6. Remove all fetch() instrumentation calls from the code
+
+## Before Starting - Check for Existing Instrumentations
+1. Call \`debug_status\` - check if server already running or port persisted
+2. Use grep to search for \`localhost:\\d+/log\` patterns in codebase
+3. If found, ensure server starts on same port to avoid breaking existing code
+
+## Tools Reference
+
+| Tool | Args | Returns |
+|------|------|---------|
+| \`debug_start\` | \`port?\` | \`{port, url, snippet, message}\` |
+| \`debug_stop\` | - | confirmation message |
+| \`debug_read\` | \`tail?\` | \`{entries: [{timestamp, label, data}, ...], count}\` |
+| \`debug_clear\` | - | confirmation message |
+| \`debug_status\` | - | \`{active, port?, url?, persistedPort?, hint?}\` |
+
+## Example Session
+
+\`\`\`
+> debug_start
+{port: 54321, url: "http://localhost:54321", snippet: "fetch(...)"}
+
+> [Insert snippet at line 42 and 67 in user's code]
+
+> [User reproduces the issue]
+
+> debug_read
+{entries: [
+  {timestamp: "...", label: "before-api", data: {userId: 123}},
+  {timestamp: "...", label: "after-api", data: {error: "timeout"}}
+], count: 2}
+
+> [Analyze: API call is timing out]
+
+> debug_stop
+{message: "Debug server stopped."}
+
+> [Remove instrumentation from lines 42 and 67]
+\`\`\``
+};
+var DebugAgentPlugin = async (ctx) => {
   return {
     tool: {
       debug_start: debugStart,
@@ -14243,22 +14304,15 @@ var DebugAgentPlugin = async () => {
       config2.agent["debug"] = {
         description: "Runtime debugging - capture and analyze execution data",
         mode: "primary",
-        prompt: agentPrompt
+        prompt: AGENT_PROMPT
       };
       const configWithSkill = config2;
       configWithSkill.skill = configWithSkill.skill ?? {};
-      for (const skill of skills) {
-        configWithSkill.skill[skill.name] = {
-          name: skill.name,
-          description: skill.description,
-          content: skill.content
-        };
-      }
+      configWithSkill.skill[DEBUG_SKILL.name] = DEBUG_SKILL;
     }
   };
 };
 var src_default = DebugAgentPlugin;
 export {
-  src_default as default,
-  DebugAgentPlugin
+  src_default as default
 };

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "opencode-debug-agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenCode plugin for runtime debugging - capture and analyze execution data",
   "author": {
     "name": "anis00723",
     "email": "anis00723@gmail.com"
   },
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,34 +17,35 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/anis-dr/opencode-debug-agent.git"
+    "url": "git+https://github.com/anis-dr/opencode-debug-agent.git"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --target bun",
+    "build": "bun build ./src/index.ts --outdir dist --target bun --format esm",
     "prepublishOnly": "bun run build"
   },
+  "opencode": {
+    "type": "plugin"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "debug",
+    "debugging",
+    "runtime"
+  ],
+  "license": "MIT",
   "dependencies": {
-    "@opencode-ai/plugin": "1.0.85",
+    "@opencode-ai/plugin": "^1.0.162",
     "hono": "^4"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^20.11.5",
-    "@typescript-eslint/eslint-plugin": "8.47.0",
-    "@typescript-eslint/parser": "8.47.0",
-    "bun-types": "latest",
-    "eslint": "^9.39.1",
-    "eslint-config-prettier": "10.1.8",
-    "eslint-plugin-prettier": "^5.1.3",
-    "prettier": "^3.2.4",
-    "typescript-eslint": "^8.47.0",
-    "vitest": "^3.2.4"
+    "@types/bun": "latest",
+    "typescript": "^5"
   }
 }

package/src/agent/debug.md

@@ -1,74 +0,0 @@
----
-description: Runtime debugging - capture and analyze execution data
-mode: primary
-tools:
-  debug_start: true
-  debug_stop: true
-  debug_read: true
-  debug_clear: true
-  debug_status: true
-  read: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
----
-
-You are a debugging specialist. Your purpose is to help users debug runtime issues by capturing and analyzing execution data.
-
-## IMPORTANT: Port Handling
-- `debug_start` returns a ready-to-use `snippet` with the correct port baked in
-- ALWAYS use the snippet from the tool response - never hardcode ports
-- If you need the current port later, call `debug_status`
-- The server remembers its port across sessions, so existing instrumentations keep working
-
-## Workflow
-
-1. Call `debug_start` to start the debug server
-2. Use the returned `snippet` to insert fetch() calls at strategic locations in the user's code
-   - Replace `LABEL_HERE` with a descriptive label (e.g., "before-api-call", "user-input", "loop-iteration")
-   - Replace `YOUR_DATA` with the variables you want to capture
-3. Ask user to reproduce the issue
-4. Call `debug_read` to analyze captured logs
-5. Identify the problem from the runtime data
-6. Call `debug_stop` when done
-7. Remove all fetch() instrumentation calls from the code
-
-## If Instrumentations Already Exist
-- Call `debug_status` first to check for existing port
-- Use `grep` to find existing `localhost:\d+/log` patterns in codebase
-- Start server on the same port to avoid breaking existing instrumentations
-
-## Example Instrumentation
-
-After calling `debug_start`, you'll get a snippet like:
-```javascript
-fetch("http://localhost:54321/log", {
-  method: "POST",
-  headers: {"Content-Type": "application/json"},
-  body: JSON.stringify({label: "LABEL_HERE", data: {YOUR_DATA}})
-})
-```
-
-Insert this at strategic points:
-```javascript
-// Before an API call
-fetch("http://localhost:54321/log", {
-  method: "POST",
-  headers: {"Content-Type": "application/json"},
-  body: JSON.stringify({label: "pre-api", data: {userId, requestBody}})
-})
-
-// After receiving response
-fetch("http://localhost:54321/log", {
-  method: "POST",
-  headers: {"Content-Type": "application/json"},
-  body: JSON.stringify({label: "post-api", data: {response, status}})
-})
-```
-
-## Tips
-- Use descriptive labels to make logs easy to understand
-- Capture relevant variables at each point
-- Add instrumentation around suspected problem areas
-- Compare expected vs actual values in the logs

package/src/command/explain.md

@@ -1,10 +0,0 @@
----
-description: Explain the current file or selection
-model: anthropic/claude-sonnet-4-20250514
----
-
-Explain the code in the current context:
-
-- What does it do?
-- How does it work?
-- Any notable patterns or techniques used?

package/src/command/format-check.md

@@ -1,6 +0,0 @@
----
-description: Check code formatting without blocking
-subtask: true
----
-
-Run the formatter check and report any files that need formatting.

package/src/command/hello.md

@@ -1,5 +0,0 @@
----
-description: A friendly greeting command
----
-
-Say hello to the user in a friendly and creative way.

package/src/command/quick-review.md

@@ -1,12 +0,0 @@
----
-description: Quick code review of staged changes
-agent: plan
----
-
-Review the staged git changes and provide:
-
-1. A brief summary of what changed
-2. Any potential issues or improvements
-3. Overall assessment (good to merge / needs work)
-
-Be concise and actionable.

package/src/index.ts

@@ -1,145 +0,0 @@
-/**
- * OpenCode Debug Agent Plugin
- *
- * Provides runtime debugging capabilities:
- * - Debug HTTP server for capturing execution data
- * - 5 tools: debug_start, debug_stop, debug_read, debug_clear, debug_status
- * - Debug agent (primary) for dedicated debugging sessions
- * - Debug skill for use with any agent
- */
-
-import type { Plugin } from '@opencode-ai/plugin';
-import path from 'path';
-import { debugStart, debugStop, debugRead, debugClear, debugStatus } from './tools';
-
-// ============================================================
-// SKILL LOADER
-// Loads SKILL.md files from src/skill/ directory
-// ============================================================
-
-interface SkillFrontmatter {
-  name: string;
-  description: string;
-}
-
-interface ParsedSkill {
-  name: string;
-  description: string;
-  content: string;
-}
-
-/**
- * Parse YAML frontmatter from a skill file
- */
-function parseSkillFrontmatter(content: string): { frontmatter: SkillFrontmatter; body: string } {
-  const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
-  const match = content.match(frontmatterRegex);
-
-  if (!match) {
-    return { frontmatter: { name: '', description: '' }, body: content.trim() };
-  }
-
-  const [, yamlContent, body] = match;
-  const frontmatter: SkillFrontmatter = { name: '', description: '' };
-
-  for (const line of yamlContent.split('\n')) {
-    const colonIndex = line.indexOf(':');
-    if (colonIndex === -1) continue;
-
-    const key = line.slice(0, colonIndex).trim();
-    const value = line.slice(colonIndex + 1).trim();
-
-    if (key === 'name') frontmatter.name = value;
-    if (key === 'description') frontmatter.description = value;
-  }
-
-  return { frontmatter, body: body.trim() };
-}
-
-/**
- * Load all skill files from the skill directory
- */
-async function loadSkills(): Promise<ParsedSkill[]> {
-  const skills: ParsedSkill[] = [];
-  const skillDir = path.join(import.meta.dir, 'skill');
-  const glob = new Bun.Glob('**/SKILL.md');
-
-  try {
-    for await (const file of glob.scan({ cwd: skillDir, absolute: true })) {
-      const content = await Bun.file(file).text();
-      const { frontmatter, body } = parseSkillFrontmatter(content);
-
-      if (frontmatter.name) {
-        skills.push({
-          name: frontmatter.name,
-          description: frontmatter.description,
-          content: body,
-        });
-      }
-    }
-  } catch {
-    // Skill directory may not exist yet
-  }
-
-  return skills;
-}
-
-/**
- * Load agent definition from markdown file
- */
-async function loadAgentPrompt(): Promise<string> {
-  try {
-    const agentFile = path.join(import.meta.dir, 'agent', 'debug.md');
-    const content = await Bun.file(agentFile).text();
-
-    // Extract body after frontmatter
-    const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
-    return match ? match[1].trim() : content;
-  } catch {
-    return 'You are a debugging specialist.';
-  }
-}
-
-export const DebugAgentPlugin: Plugin = async () => {
-  // Load skills at initialization
-  const skills = await loadSkills();
-  const agentPrompt = await loadAgentPrompt();
-
-  return {
-    // Register debug tools
-    tool: {
-      debug_start: debugStart,
-      debug_stop: debugStop,
-      debug_read: debugRead,
-      debug_clear: debugClear,
-      debug_status: debugStatus,
-    },
-
-    // Config hook to inject agent and skills
-    async config(config) {
-      // Inject debug agent
-      config.agent = config.agent ?? {};
-      config.agent['debug'] = {
-        description: 'Runtime debugging - capture and analyze execution data',
-        mode: 'primary',
-        prompt: agentPrompt,
-      };
-
-      // Inject skills (using type assertion as skill may not be in Config type yet)
-      const configWithSkill = config as typeof config & {
-        skill?: Record<string, { name: string; description: string; content: string }>;
-      };
-      configWithSkill.skill = configWithSkill.skill ?? {};
-      for (const skill of skills) {
-        configWithSkill.skill[skill.name] = {
-          name: skill.name,
-          description: skill.description,
-          content: skill.content,
-        };
-      }
-    },
-  };
-};
-
-// Default export for compatibility
-export default DebugAgentPlugin;

package/src/server.ts

@@ -1,267 +0,0 @@
-/**
- * Debug Server - Hono-based HTTP server for capturing runtime debug data
- *
- * Features:
- * - CORS enabled for browser instrumentation
- * - Port persistence across sessions
- * - NDJSON log format
- * - Auto-flush with configurable interval
- */
-
-import { Hono } from 'hono';
-import { cors } from 'hono/cors';
-import { mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
-
-interface LogEntry {
-  timestamp: string;
-  label: string;
-  data: unknown;
-}
-
-interface StartResult {
-  port: number;
-  url: string;
-}
-
-interface ServerInfo {
-  active: boolean;
-  port?: number;
-  url?: string;
-}
-
-class DebugServer {
-  private server: ReturnType<typeof Bun.serve> | null = null;
-  private writer: ReturnType<(typeof Bun.file)['prototype']['writer']> | null = null;
-  private flushInterval: ReturnType<typeof setInterval> | null = null;
-
-  private portFile = '.opencode/debug.port';
-  private logFile = '.opencode/debug.log';
-
-  /**
-   * Start the debug server
-   * Port priority: 1) User-specified → 2) Persisted port → 3) Auto-select
-   */
-  async start(port?: number): Promise<StartResult> {
-    // If already running, return existing info
-    if (this.server) {
-      const existingPort = this.server.port ?? 0;
-      return {
-        port: existingPort,
-        url: `http://localhost:${existingPort}`,
-      };
-    }
-
-    // Determine target port
-    const targetPort = port ?? (await this.loadPersistedPort()) ?? 0;
-
-    // Create Hono app
-    const app = new Hono();
-
-    // Enable CORS for browser instrumentation
-    app.use(
-      '/*',
-      cors({
-        origin: '*',
-        allowMethods: ['POST', 'GET', 'OPTIONS'],
-        allowHeaders: ['Content-Type'],
-      })
-    );
-
-    // POST /log - receive debug data
-    app.post('/log', async (c) => {
-      try {
-        const body = await c.req.json();
-        const entry: LogEntry = {
-          timestamp: new Date().toISOString(),
-          label: body.label ?? 'unknown',
-          data: body.data ?? body,
-        };
-        await this.appendLog(entry);
-        return c.json({ success: true });
-      } catch (error) {
-        return c.json({ error: 'Invalid JSON' }, 400);
-      }
-    });
-
-    // GET /health - health check
-    app.get('/health', (c) => c.text('OK'));
-
-    // Ensure .opencode directory exists
-    await mkdir(dirname(this.logFile), { recursive: true });
-
-    // Initialize log file writer
-    const file = Bun.file(this.logFile);
-    this.writer = file.writer({ highWaterMark: 1024 * 8 });
-
-    // Start server
-    this.server = Bun.serve({
-      fetch: app.fetch,
-      port: targetPort,
-    });
-
-    // Get the actual port (Bun may have assigned one if we requested 0)
-    const actualPort = this.server.port ?? 0;
-
-    // Persist the port for future sessions
-    await this.persistPort(actualPort);
-
-    // Auto-flush every 5 seconds
-    this.flushInterval = setInterval(() => {
-      this.writer?.flush();
-    }, 5000);
-
-    return {
-      port: actualPort,
-      url: `http://localhost:${actualPort}`,
-    };
-  }
-
-  /**
-   * Stop the debug server
-   */
-  async stop(): Promise<void> {
-    if (this.flushInterval) {
-      clearInterval(this.flushInterval);
-      this.flushInterval = null;
-    }
-
-    if (this.writer) {
-      await this.writer.flush();
-      await this.writer.end();
-      this.writer = null;
-    }
-
-    if (this.server) {
-      this.server.stop();
-      this.server = null;
-    }
-  }
-
-  /**
-   * Check if server is running
-   */
-  isRunning(): boolean {
-    return this.server !== null;
-  }
-
-  /**
-   * Get current server info
-   */
-  getInfo(): ServerInfo {
-    if (!this.server) {
-      return { active: false };
-    }
-    return {
-      active: true,
-      port: this.server.port,
-      url: `http://localhost:${this.server.port}`,
-    };
-  }
-
-  /**
-   * Get persisted port (for when server is not running)
-   */
-  async getPersistedPort(): Promise<number | null> {
-    return this.loadPersistedPort();
-  }
-
-  /**
-   * Read log entries
-   */
-  async readLogs(tail?: number): Promise<LogEntry[]> {
-    try {
-      // Flush before reading to ensure all data is written
-      await this.writer?.flush();
-
-      const file = Bun.file(this.logFile);
-      if (!(await file.exists())) {
-        return [];
-      }
-
-      const content = await file.text();
-      const lines = content.trim().split('\n').filter(Boolean);
-
-      const entries: LogEntry[] = [];
-      for (const line of lines) {
-        try {
-          entries.push(JSON.parse(line));
-        } catch {
-          // Skip malformed lines
-        }
-      }
-
-      if (tail && tail > 0) {
-        return entries.slice(-tail);
-      }
-
-      return entries;
-    } catch {
-      return [];
-    }
-  }
-
-  /**
-   * Clear log file
-   */
-  async clearLogs(): Promise<void> {
-    // Stop current writer if exists
-    if (this.writer) {
-      await this.writer.flush();
-      await this.writer.end();
-    }
-
-    // Truncate the file
-    await Bun.write(this.logFile, '');
-
-    // Restart writer if server is running
-    if (this.server) {
-      const file = Bun.file(this.logFile);
-      this.writer = file.writer({ highWaterMark: 1024 * 8 });
-    }
-  }
-
-  /**
-   * Append a log entry
-   */
-  private async appendLog(entry: LogEntry): Promise<void> {
-    if (!this.writer) {
-      // Server not running, append directly to file
-      await mkdir(dirname(this.logFile), { recursive: true });
-      const file = Bun.file(this.logFile);
-      const existing = (await file.exists()) ? await file.text() : '';
-      await Bun.write(this.logFile, existing + JSON.stringify(entry) + '\n');
-      return;
-    }
-
-    this.writer.write(JSON.stringify(entry) + '\n');
-  }
-
-  /**
-   * Load persisted port from file
-   */
-  private async loadPersistedPort(): Promise<number | null> {
-    try {
-      const file = Bun.file(this.portFile);
-      if (!(await file.exists())) {
-        return null;
-      }
-      const content = await file.text();
-      const port = parseInt(content.trim(), 10);
-      return isNaN(port) ? null : port;
-    } catch {
-      return null;
-    }
-  }
-
-  /**
-   * Persist port to file
-   */
-  private async persistPort(port: number): Promise<void> {
-    await mkdir(dirname(this.portFile), { recursive: true });
-    await Bun.write(this.portFile, String(port));
-  }
-}
-
-// Singleton instance
-export const debugServer = new DebugServer();

package/src/skill/debug/SKILL.md

@@ -1,60 +0,0 @@
----
-name: debug
-description: Runtime debugging - start a debug server, instrument code with fetch() calls, capture and analyze execution data
----
-
-## CRITICAL: Port Handling
-- `debug_start` returns a `snippet` with the correct port - ALWAYS use it
-- Never hardcode ports in fetch() calls
-- Call `debug_status` to get current port if needed later
-- Server persists port to `.opencode/debug.port` so existing instrumentations keep working
-
-## Workflow
-
-1. `debug_start` - Returns {port, url, snippet}
-2. Insert the returned `snippet` at strategic code locations:
-   - Replace `LABEL_HERE` with descriptive label (e.g., "before-api", "after-parse")
-   - Replace `YOUR_DATA` with variables to capture (e.g., `{userId, response}`)
-3. Ask user to reproduce the issue
-4. `debug_read` - Analyze captured logs (returns parsed JSON array)
-5. `debug_stop` - Stop server when done
-6. Remove all fetch() instrumentation calls from the code
-
-## Before Starting - Check for Existing Instrumentations
-1. Call `debug_status` - check if server already running or port persisted
-2. Use grep to search for `localhost:\d+/log` patterns in codebase
-3. If found, ensure server starts on same port to avoid breaking existing code
-
-## Tools Reference
-
-| Tool | Args | Returns |
-|------|------|---------|
-| `debug_start` | `port?` | `{port, url, snippet, message}` |
-| `debug_stop` | - | confirmation message |
-| `debug_read` | `tail?` | `{entries: [{timestamp, label, data}, ...], count}` |
-| `debug_clear` | - | confirmation message |
-| `debug_status` | - | `{active, port?, url?, persistedPort?, hint?}` |
-
-## Example Session
-
-```
-> debug_start
-{port: 54321, url: "http://localhost:54321", snippet: "fetch(...)"}
-
-> [Insert snippet at line 42 and 67 in user's code]
-
-> [User reproduces the issue]
-
-> debug_read
-{entries: [
-  {timestamp: "...", label: "before-api", data: {userId: 123}},
-  {timestamp: "...", label: "after-api", data: {error: "timeout"}}
-], count: 2}
-
-> [Analyze: API call is timing out]
-
-> debug_stop
-{message: "Debug server stopped."}
-
-> [Remove instrumentation from lines 42 and 67]
-```

package/src/tools.ts

@@ -1,131 +0,0 @@
-/**
- * Debug Tools - OpenCode tools for runtime debugging workflow
- */
-
-import { tool } from '@opencode-ai/plugin';
-import { debugServer } from './server';
-
-/**
- * Generate the instrumentation snippet with the given URL
- */
-function generateSnippet(url: string): string {
-  return `fetch("${url}/log", {
-  method: "POST",
-  headers: {"Content-Type": "application/json"},
-  body: JSON.stringify({label: "LABEL_HERE", data: {YOUR_DATA}})
-})`;
-}
-
-/**
- * Start debug server to capture runtime data
- * Returns port, URL, and ready-to-use code snippet
- */
-export const debugStart = tool({
-  description:
-    'Start debug server to capture runtime data. Returns port, URL, and ready-to-use code snippet for instrumentation.',
-  args: {
-    port: tool.schema
-      .number()
-      .optional()
-      .describe(
-        'Specific port to use (optional). If not provided, reuses previous port or auto-selects.'
-      ),
-  },
-  async execute(args) {
-    const result = await debugServer.start(args.port);
-    return JSON.stringify({
-      port: result.port,
-      url: result.url,
-      snippet: generateSnippet(result.url),
-      message: `Debug server running on port ${result.port}. Use the snippet to instrument code.`,
-    });
-  },
-});
-
-/**
- * Stop the debug server and flush remaining logs
- */
-export const debugStop = tool({
-  description: 'Stop the debug server and flush remaining logs to disk.',
-  args: {},
-  async execute() {
-    if (!debugServer.isRunning()) {
-      return JSON.stringify({ message: 'Debug server is not running.' });
-    }
-    await debugServer.stop();
-    return JSON.stringify({
-      message: 'Debug server stopped. Logs preserved in .opencode/debug.log',
-    });
-  },
-});
-
-/**
- * Read captured debug logs
- */
-export const debugRead = tool({
-  description: 'Read captured debug logs. Returns parsed JSON array of log entries.',
-  args: {
-    tail: tool.schema
-      .number()
-      .optional()
-      .describe('Return only the last N entries. If not provided, returns all entries.'),
-  },
-  async execute(args) {
-    const entries = await debugServer.readLogs(args.tail);
-    if (entries.length === 0) {
-      return JSON.stringify({
-        entries: [],
-        message:
-          'No log entries found. Make sure the debug server is running and code is instrumented.',
-      });
-    }
-    return JSON.stringify({
-      entries,
-      count: entries.length,
-    });
-  },
-});
-
-/**
- * Clear the debug log file
- */
-export const debugClear = tool({
-  description: 'Clear the debug log file.',
-  args: {},
-  async execute() {
-    await debugServer.clearLogs();
-    return JSON.stringify({ message: 'Debug log cleared.' });
-  },
-});
-
-/**
- * Check debug server status and get current port/URL
- */
-export const debugStatus = tool({
-  description:
-    'Check if debug server is running and get current port/URL. Also shows persisted port from previous sessions.',
-  args: {},
-  async execute() {
-    const info = debugServer.getInfo();
-
-    if (info.active && info.url) {
-      return JSON.stringify({
-        active: true,
-        port: info.port,
-        url: info.url,
-        snippet: generateSnippet(info.url),
-      });
-    }
-
-    // Server not running - check for persisted port
-    const persistedPort = await debugServer.getPersistedPort();
-
-    return JSON.stringify({
-      active: false,
-      persistedPort,
-      hint: persistedPort
-        ? `Previous session used port ${persistedPort}. Call debug_start to reuse it.`
-        : 'No debug server configured. Call debug_start to begin.',
-    });
-  },
-});