opencode-debug-agent 0.1.0 → 0.1.1

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, {
@@ -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 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 () => {
-  const skills = await loadSkills();
-  const agentPrompt = await loadAgentPrompt();
   return {
     tool: {
       debug_start: debugStart,
@@ -14243,17 +14304,11 @@ 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;
     }
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-debug-agent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "OpenCode plugin for runtime debugging - capture and analyze execution data",
   "author": {
     "name": "anis00723",

package/src/index.ts

@@ -9,102 +9,137 @@
  */
 
 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
+// EMBEDDED CONTENT (to avoid file loading issues in npm packages)
 // ============================================================
 
-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;
-}
+const 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`;
+
+const 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]
+\`\`\``,
+};
 
-/**
- * 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.';
-  }
-}
+// ============================================================
+// PLUGIN EXPORT
+// ============================================================
 
 export const DebugAgentPlugin: Plugin = async () => {
-  // Load skills at initialization
-  const skills = await loadSkills();
-  const agentPrompt = await loadAgentPrompt();
-
   return {
     // Register debug tools
     tool: {
@@ -122,7 +157,7 @@ export const DebugAgentPlugin: Plugin = async () => {
       config.agent['debug'] = {
         description: 'Runtime debugging - capture and analyze execution data',
         mode: 'primary',
-        prompt: agentPrompt,
+        prompt: AGENT_PROMPT,
       };
 
       // Inject skills (using type assertion as skill may not be in Config type yet)
@@ -130,13 +165,7 @@ export const DebugAgentPlugin: Plugin = async () => {
         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,
-        };
-      }
+      configWithSkill.skill[DEBUG_SKILL.name] = DEBUG_SKILL;
     },
   };
 };