opencode-swarm-plugin 0.12.19 → 0.12.22

package/scripts/init-skill.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+/**
+ * Skill Initializer - Creates a new skill from template
+ *
+ * Usage:
+ *   bun scripts/init-skill.ts <skill-name> [--path <path>] [--global]
+ *
+ * Examples:
+ *   bun scripts/init-skill.ts my-skill
+ *   bun scripts/init-skill.ts my-skill --path .claude/skills
+ *   bun scripts/init-skill.ts my-skill --global
+ */
+
+import { mkdir, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join } from "path";
+import { parseArgs } from "util";
+
+const SKILL_TEMPLATE = (name: string, title: string) => `---
+name: ${name}
+description: [TODO: Complete description of what this skill does and WHEN to use it. Be specific about scenarios that trigger this skill.]
+tags:
+  - [TODO: add tags]
+---
+
+# ${title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## When to Use This Skill
+
+[TODO: List specific scenarios when this skill should be activated:
+- When working on X type of task
+- When files matching Y pattern are involved
+- When the user asks about Z topic]
+
+## Instructions
+
+[TODO: Add actionable instructions for the agent. Use imperative form:
+- "Read the configuration file first"
+- "Check for existing patterns before creating new ones"
+- "Always validate output before completing"]
+
+## Examples
+
+### Example 1: [TODO: Realistic scenario]
+
+**User**: "[TODO: Example user request]"
+
+**Process**:
+1. [TODO: Step-by-step process]
+2. [TODO: Next step]
+3. [TODO: Final step]
+
+## Resources
+
+This skill may include additional resources:
+
+### scripts/
+Executable scripts for automation. Run with \`skills_execute\`.
+
+### references/
+Documentation loaded on-demand. Access with \`skills_read\`.
+
+---
+*Delete any unused sections and this line when skill is complete.*
+`;
+
+const EXAMPLE_SCRIPT = (name: string) => `#!/usr/bin/env bash
+# Example helper script for ${name}
+#
+# This is a placeholder. Replace with actual implementation or delete.
+#
+# Usage: skills_execute(skill: "${name}", script: "example.sh")
+
+echo "Hello from ${name} skill!"
+echo "Project directory: $1"
+
+# TODO: Add actual script logic
+`;
+
+const REFERENCE_TEMPLATE = (title: string) => `# Reference Documentation for ${title}
+
+## Overview
+
+[TODO: Detailed reference material for this skill]
+
+## API Reference
+
+[TODO: If applicable, document APIs, schemas, or interfaces]
+
+## Detailed Workflows
+
+[TODO: Complex multi-step workflows that don't fit in SKILL.md]
+
+## Troubleshooting
+
+[TODO: Common issues and solutions]
+`;
+
+function titleCase(name: string): string {
+  return name
+    .split("-")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+async function initSkill(
+  name: string,
+  basePath: string,
+  isGlobal: boolean
+): Promise<void> {
+  // Validate name
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    console.error("❌ Error: Skill name must be lowercase with hyphens only");
+    process.exit(1);
+  }
+
+  if (name.length > 64) {
+    console.error("❌ Error: Skill name must be 64 characters or less");
+    process.exit(1);
+  }
+
+  // Determine target directory
+  let skillDir: string;
+  if (isGlobal) {
+    const home = process.env.HOME || process.env.USERPROFILE || "~";
+    skillDir = join(home, ".config", "opencode", "skills", name);
+  } else {
+    skillDir = join(basePath, name);
+  }
+
+  // Check if exists
+  if (existsSync(skillDir)) {
+    console.error(`❌ Error: Skill directory already exists: ${skillDir}`);
+    process.exit(1);
+  }
+
+  const title = titleCase(name);
+  const createdFiles: string[] = [];
+
+  try {
+    // Create skill directory
+    await mkdir(skillDir, { recursive: true });
+    console.log(`✅ Created skill directory: ${skillDir}`);
+
+    // Create SKILL.md
+    const skillPath = join(skillDir, "SKILL.md");
+    await writeFile(skillPath, SKILL_TEMPLATE(name, title));
+    createdFiles.push("SKILL.md");
+    console.log("✅ Created SKILL.md");
+
+    // Create scripts/ directory with example
+    const scriptsDir = join(skillDir, "scripts");
+    await mkdir(scriptsDir, { recursive: true });
+    const scriptPath = join(scriptsDir, "example.sh");
+    await writeFile(scriptPath, EXAMPLE_SCRIPT(name), { mode: 0o755 });
+    createdFiles.push("scripts/example.sh");
+    console.log("✅ Created scripts/example.sh");
+
+    // Create references/ directory with example
+    const refsDir = join(skillDir, "references");
+    await mkdir(refsDir, { recursive: true });
+    const refPath = join(refsDir, "guide.md");
+    await writeFile(refPath, REFERENCE_TEMPLATE(title));
+    createdFiles.push("references/guide.md");
+    console.log("✅ Created references/guide.md");
+
+    console.log(`\n✅ Skill '${name}' initialized successfully at ${skillDir}`);
+    console.log("\nNext steps:");
+    console.log("  1. Edit SKILL.md to complete TODO placeholders");
+    console.log("  2. Update the description in frontmatter");
+    console.log("  3. Add specific 'When to Use' scenarios");
+    console.log("  4. Delete unused sections and placeholder files");
+    console.log("  5. Test with skills_use to verify it works");
+  } catch (error) {
+    console.error(
+      `❌ Error: ${error instanceof Error ? error.message : String(error)}`
+    );
+    process.exit(1);
+  }
+}
+
+// Parse arguments
+const { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    path: { type: "string", default: ".opencode/skills" },
+    global: { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+  },
+  allowPositionals: true,
+});
+
+if (values.help || positionals.length === 0) {
+  console.log(`
+Skill Initializer - Creates a new skill from template
+
+Usage:
+  bun scripts/init-skill.ts <skill-name> [options]
+
+Options:
+  --path <path>   Directory to create skill in (default: .opencode/skills)
+  --global        Create in global ~/.config/opencode/skills directory
+  -h, --help      Show this help message
+
+Examples:
+  bun scripts/init-skill.ts my-skill
+  bun scripts/init-skill.ts my-skill --path .claude/skills
+  bun scripts/init-skill.ts my-skill --global
+
+Skill name requirements:
+  - Lowercase letters, digits, and hyphens only
+  - Max 64 characters
+`);
+  process.exit(values.help ? 0 : 1);
+}
+
+const skillName = positionals[0];
+await initSkill(skillName, values.path!, values.global!);

package/scripts/validate-skill.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+/**
+ * Skill Validator - Validates skill structure and content
+ *
+ * Usage:
+ *   bun scripts/validate-skill.ts <path/to/skill>
+ *
+ * Examples:
+ *   bun scripts/validate-skill.ts .opencode/skills/my-skill
+ *   bun scripts/validate-skill.ts global-skills/debugging
+ */
+
+import { readFile, readdir } from "fs/promises";
+import { existsSync } from "fs";
+import { join, basename } from "path";
+import { parseFrontmatter } from "../src/skills.js";
+
+interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  info: string[];
+}
+
+async function validateSkill(skillPath: string): Promise<ValidationResult> {
+  const result: ValidationResult = {
+    valid: true,
+    errors: [],
+    warnings: [],
+    info: [],
+  };
+
+  const skillName = basename(skillPath);
+
+  // Check directory exists
+  if (!existsSync(skillPath)) {
+    result.errors.push(`Skill directory does not exist: ${skillPath}`);
+    result.valid = false;
+    return result;
+  }
+
+  // Check SKILL.md exists
+  const skillMdPath = join(skillPath, "SKILL.md");
+  if (!existsSync(skillMdPath)) {
+    result.errors.push("Missing required SKILL.md file");
+    result.valid = false;
+    return result;
+  }
+
+  // Read and parse SKILL.md
+  const content = await readFile(skillMdPath, "utf-8");
+
+  // Check frontmatter
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) {
+    result.errors.push("SKILL.md must start with YAML frontmatter (---)");
+    result.valid = false;
+    return result;
+  }
+
+  const { metadata: frontmatter, body } = parseFrontmatter(content);
+  if (Object.keys(frontmatter).length === 0) {
+    result.errors.push("Invalid YAML frontmatter format");
+    result.valid = false;
+    return result;
+  }
+
+  // Validate required fields
+  if (!frontmatter.name) {
+    result.errors.push("Missing required 'name' field in frontmatter");
+    result.valid = false;
+  } else if (frontmatter.name !== skillName) {
+    result.warnings.push(
+      `Frontmatter name '${frontmatter.name}' doesn't match directory name '${skillName}'`,
+    );
+  }
+
+  if (!frontmatter.description) {
+    result.errors.push("Missing required 'description' field in frontmatter");
+    result.valid = false;
+  } else {
+    const desc = String(frontmatter.description);
+    if (desc.includes("[TODO")) {
+      result.warnings.push("Description contains TODO placeholder");
+    }
+    if (desc.length < 20) {
+      result.warnings.push("Description is very short (< 20 chars)");
+    }
+    if (desc.length > 500) {
+      result.warnings.push("Description is very long (> 500 chars)");
+    }
+  }
+
+  // Check for TODO placeholders in body
+  const todoCount = (body.match(/\[TODO/g) || []).length;
+  if (todoCount > 0) {
+    result.warnings.push(`Found ${todoCount} TODO placeholder(s) in body`);
+  }
+
+  // Check body length (body is already extracted by parseFrontmatter)
+  const lineCount = body.split("\n").length;
+  if (lineCount > 500) {
+    result.warnings.push(
+      `SKILL.md body is ${lineCount} lines (recommended < 500)`,
+    );
+  }
+
+  // Check for optional directories
+  const scriptsDir = join(skillPath, "scripts");
+  const refsDir = join(skillPath, "references");
+  const assetsDir = join(skillPath, "assets");
+
+  if (existsSync(scriptsDir)) {
+    const scripts = await readdir(scriptsDir);
+    result.info.push(`Found ${scripts.length} script(s) in scripts/`);
+
+    // Check for example placeholders
+    if (scripts.includes("example.sh") || scripts.includes("example.py")) {
+      result.warnings.push("Contains placeholder example script");
+    }
+  }
+
+  if (existsSync(refsDir)) {
+    const refs = await readdir(refsDir);
+    result.info.push(`Found ${refs.length} reference(s) in references/`);
+  }
+
+  if (existsSync(assetsDir)) {
+    const assets = await readdir(assetsDir);
+    result.info.push(`Found ${assets.length} asset(s) in assets/`);
+  }
+
+  // Check for unwanted files
+  const unwantedFiles = [
+    "README.md",
+    "CHANGELOG.md",
+    "INSTALLATION.md",
+    "CONTRIBUTING.md",
+  ];
+  for (const file of unwantedFiles) {
+    if (existsSync(join(skillPath, file))) {
+      result.warnings.push(
+        `Found ${file} - skills should only contain SKILL.md and resources`,
+      );
+    }
+  }
+
+  return result;
+}
+
+// Main
+const skillPath = process.argv[2];
+
+if (!skillPath) {
+  console.log(`
+Skill Validator - Validates skill structure and content
+
+Usage:
+  bun scripts/validate-skill.ts <path/to/skill>
+
+Examples:
+  bun scripts/validate-skill.ts .opencode/skills/my-skill
+  bun scripts/validate-skill.ts global-skills/debugging
+`);
+  process.exit(1);
+}
+
+console.log(`Validating skill: ${skillPath}\n`);
+
+const result = await validateSkill(skillPath);
+
+// Print results
+if (result.errors.length > 0) {
+  console.log("❌ Errors:");
+  for (const error of result.errors) {
+    console.log(`   - ${error}`);
+  }
+  console.log();
+}
+
+if (result.warnings.length > 0) {
+  console.log("⚠️  Warnings:");
+  for (const warning of result.warnings) {
+    console.log(`   - ${warning}`);
+  }
+  console.log();
+}
+
+if (result.info.length > 0) {
+  console.log("ℹ️  Info:");
+  for (const info of result.info) {
+    console.log(`   - ${info}`);
+  }
+  console.log();
+}
+
+if (result.valid) {
+  console.log("✅ Skill is valid!");
+  if (result.warnings.length > 0) {
+    console.log("   (but consider addressing warnings above)");
+  }
+} else {
+  console.log("❌ Skill validation failed");
+  process.exit(1);
+}

package/src/agent-mail.integration.test.ts

@@ -11,12 +11,15 @@
 import { describe, it, expect, beforeAll } from "vitest";
 import {
   mcpCall,
+  mcpCallWithAutoInit,
   sessionStates,
   setState,
   clearState,
   requireState,
   MAX_INBOX_LIMIT,
   AgentMailNotInitializedError,
+  isProjectNotFoundError,
+  isAgentNotFoundError,
   type AgentMailState,
 } from "./agent-mail";
 
@@ -1318,4 +1321,109 @@ describe("agent-mail integration", () => {
       clearState(worker2Ctx.sessionID);
     });
   });
+
+  // ============================================================================
+  // Self-Healing Tests (mcpCallWithAutoInit)
+  // ============================================================================
+
+  describe("self-healing (mcpCallWithAutoInit)", () => {
+    it("detects project not found errors correctly", () => {
+      const projectError = new Error("Project 'migrate-egghead' not found.");
+      const agentError = new Error("Agent 'BlueLake' not found in project");
+      const otherError = new Error("Network timeout");
+
+      expect(isProjectNotFoundError(projectError)).toBe(true);
+      expect(isProjectNotFoundError(agentError)).toBe(false);
+      expect(isProjectNotFoundError(otherError)).toBe(false);
+
+      expect(isAgentNotFoundError(agentError)).toBe(true);
+      expect(isAgentNotFoundError(projectError)).toBe(false);
+      expect(isAgentNotFoundError(otherError)).toBe(false);
+    });
+
+    it("auto-registers project on 'not found' error", async () => {
+      const ctx = createTestContext();
+
+      // First, ensure project exists and register an agent
+      const { state } = await initTestAgent(ctx, `AutoInit_${Date.now()}`);
+
+      // Now use mcpCallWithAutoInit - it should work normally
+      // (no error to recover from, but verifies the wrapper works)
+      await mcpCallWithAutoInit("send_message", {
+        project_key: state.projectKey,
+        agent_name: state.agentName,
+        sender_name: state.agentName,
+        to: [],
+        subject: "Test auto-init wrapper",
+        body_md: "This should work normally",
+        thread_id: "test-thread",
+        importance: "normal",
+      });
+
+      // Verify message was sent by checking inbox
+      const inbox = await mcpCall<Array<{ subject: string }>>("fetch_inbox", {
+        project_key: state.projectKey,
+        agent_name: state.agentName,
+        limit: 5,
+        include_bodies: false,
+      });
+
+      // The message should be in the inbox (sent to empty 'to' = broadcast)
+      // Note: depending on Agent Mail behavior, broadcast might not show in sender's inbox
+      // This test mainly verifies the wrapper doesn't break normal operation
+
+      // Cleanup
+      clearState(ctx.sessionID);
+    });
+
+    it("recovers from simulated project not found by re-registering", async () => {
+      const ctx = createTestContext();
+
+      // Create a fresh project key that doesn't exist yet
+      const freshProjectKey = `/test/fresh-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const agentName = `Recovery_${Date.now()}`;
+
+      // First ensure the project exists (simulating initial setup)
+      await mcpCall("ensure_project", { human_key: freshProjectKey });
+      await mcpCall("register_agent", {
+        project_key: freshProjectKey,
+        program: "opencode-test",
+        model: "test-model",
+        name: agentName,
+        task_description: "Recovery test agent",
+      });
+
+      // Now use mcpCallWithAutoInit for an operation
+      // This should work, and if the project somehow got lost, it would re-register
+      await mcpCallWithAutoInit("send_message", {
+        project_key: freshProjectKey,
+        agent_name: agentName,
+        sender_name: agentName,
+        to: [],
+        subject: "Recovery test",
+        body_md: "Testing self-healing",
+        thread_id: "recovery-test",
+        importance: "normal",
+      });
+
+      // If we got here without error, the wrapper is working
+      // (In a real scenario where the server restarted, it would have re-registered)
+    });
+
+    it("passes through non-recoverable errors", async () => {
+      const ctx = createTestContext();
+      const { state } = await initTestAgent(ctx, `ErrorPass_${Date.now()}`);
+
+      // Try to call a non-existent tool - should throw, not retry forever
+      await expect(
+        mcpCallWithAutoInit("nonexistent_tool_xyz", {
+          project_key: state.projectKey,
+          agent_name: state.agentName,
+        }),
+      ).rejects.toThrow(/Unknown tool/);
+
+      // Cleanup
+      clearState(ctx.sessionID);
+    });
+  });
 });