opencode-swarm-plugin 0.32.0 → 0.34.0

package/src/skills.integration.test.ts

@@ -16,7 +16,7 @@
  * - skills_execute
  */
 
-import { describe, expect, it, afterAll, beforeEach } from "vitest";
+import { describe, expect, it, afterAll, beforeEach, vi } from "vitest";
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -1054,3 +1054,139 @@ describe("skills_execute tool", () => {
     expect(result).toContain("60 seconds");
   }, 65000); // Allow 65s for test itself
 });
+
+// =============================================================================
+// Deprecation Warnings Tests
+// =============================================================================
+
+describe("deprecation warnings", () => {
+  beforeEach(() => {
+    setupTestDir();
+  });
+
+  afterAll(() => {
+    cleanupTestDir();
+  });
+
+  it("skills_list emits deprecation warning", async () => {
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await skills_list.execute({});
+    
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[DEPRECATED] skills_list")
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("OpenCode now provides native skills support")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("skills_use emits deprecation warning", async () => {
+    await skills_create.execute({
+      name: "test-skill",
+      description: "Use when testing",
+      body: "Instructions",
+    });
+
+    invalidateSkillsCache();
+    
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await skills_use.execute({ name: "test-skill" });
+    
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[DEPRECATED] skills_use")
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("OpenCode now provides native skills support")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("skills_read emits deprecation warning", async () => {
+    await skills_create.execute({
+      name: "test-skill",
+      description: "Use when testing",
+      body: "Instructions",
+    });
+
+    const skillDir = join(SKILLS_DIR, "test-skill");
+    writeFileSync(join(skillDir, "example.md"), "# Example");
+
+    invalidateSkillsCache();
+    
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await skills_read.execute({
+      skill: "test-skill",
+      file: "example.md",
+    });
+    
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[DEPRECATED] skills_read")
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("OpenCode now provides native skills support")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("skills_execute emits deprecation warning", async () => {
+    await skills_create.execute({
+      name: "test-skill",
+      description: "Use when testing",
+      body: "Instructions",
+    });
+
+    await skills_add_script.execute({
+      skill: "test-skill",
+      script_name: "test.sh",
+      content: '#!/bin/bash\necho "test"',
+    });
+
+    const scriptPath = join(SKILLS_DIR, "test-skill", "scripts", "test.sh");
+    chmodSync(scriptPath, 0o755);
+
+    invalidateSkillsCache();
+    
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await skills_execute.execute({
+      skill: "test-skill",
+      script: "test.sh",
+    });
+    
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("[DEPRECATED] skills_execute")
+    );
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining("OpenCode now provides native skills support")
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("deprecated tools still function correctly (soft deprecation)", async () => {
+    // Create a skill
+    await skills_create.execute({
+      name: "functional-test",
+      description: "Use when testing functionality",
+      body: "# Test\n\nStill works!",
+    });
+
+    invalidateSkillsCache();
+
+    // Suppress console.warn for this test
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    // skills_list should still list skills
+    const listResult = await skills_list.execute({});
+    expect(listResult).toContain("functional-test");
+
+    // skills_use should still return content
+    const useResult = await skills_use.execute({ name: "functional-test" });
+    expect(useResult).toContain("Still works!");
+
+    warnSpy.mockRestore();
+  });
+});

package/src/skills.test.ts

@@ -8,7 +8,7 @@
  * - ES module compatibility
  */
 
-import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";
 import { join, resolve, relative } from "path";
 import { mkdirSync, writeFileSync, rmSync, existsSync } from "fs";
 import {
@@ -551,6 +551,47 @@ describe("validateCSOCompliance", () => {
   });
 });
 
+// ============================================================================
+// Tests: Deprecation Warnings
+// ============================================================================
+
+describe("deprecation warnings", () => {
+  beforeEach(() => {
+    cleanupTestSkillsDir();
+    setupTestSkillsDir();
+    setSkillsProjectDirectory(TEST_DIR);
+    invalidateSkillsCache();
+  });
+
+  afterEach(() => {
+    cleanupTestSkillsDir();
+    invalidateSkillsCache();
+  });
+
+  it("listSkills emits deprecation warning", async () => {
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await listSkills();
+    
+    // Verify warning was emitted (for listSkills internal function)
+    // The actual tool warning happens in skills_list tool execute
+    warnSpy.mockRestore();
+  });
+
+  it("getSkill does NOT emit deprecation warning (internal function)", async () => {
+    const warnSpy = vi.spyOn(console, "warn");
+    
+    await getSkill("test-skill");
+    
+    // getSkill is internal, should not have DEPRECATED warnings
+    const deprecationCalls = warnSpy.mock.calls.filter(call => 
+      call.some(arg => String(arg).includes("[DEPRECATED]"))
+    );
+    expect(deprecationCalls.length).toBe(0);
+    warnSpy.mockRestore();
+  });
+});
+
 // ============================================================================
 // Tests: Edge Cases
 // ============================================================================

package/src/skills.ts

@@ -399,7 +399,7 @@ export function invalidateSkillsCache(): void {
  * which skills are relevant to the current task.
  */
 export const skills_list = tool({
-  description: `List all available skills in the project.
+  description: `[DEPRECATED] List all available skills in the project.
 
 Skills are specialized instructions that help with specific domains or tasks.
 Use this tool to discover what skills are available, then use skills_use to
@@ -413,6 +413,7 @@ Returns skill names, descriptions, and whether they have executable scripts.`,
       .describe("Optional tag to filter skills by"),
   },
   async execute(args) {
+    console.warn('[DEPRECATED] skills_list is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.');
     const skills = await discoverSkills();
     let refs = Array.from(skills.values());
 
@@ -448,7 +449,7 @@ Returns skill names, descriptions, and whether they have executable scripts.`,
  * The skill's instructions become available for the model to follow.
  */
 export const skills_use = tool({
-  description: `Activate a skill by loading its full instructions.
+  description: `[DEPRECATED] Activate a skill by loading its full instructions.
 
 After calling this tool, follow the skill's instructions for the current task.
 Skills provide domain-specific guidance and best practices.
@@ -462,6 +463,7 @@ If the skill has scripts, you can run them with skills_execute.`,
       .describe("Also list available scripts (default: true)"),
   },
   async execute(args) {
+    console.warn('[DEPRECATED] skills_use is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.');
     const skill = await getSkill(args.name);
 
     if (!skill) {
@@ -492,7 +494,7 @@ If the skill has scripts, you can run them with skills_execute.`,
  * This tool runs them with appropriate context.
  */
 export const skills_execute = tool({
-  description: `Execute a script from a skill's scripts/ directory.
+  description: `[DEPRECATED] Execute a script from a skill's scripts/ directory.
 
 Some skills include helper scripts for common operations.
 Use skills_use first to see available scripts, then execute them here.
@@ -507,6 +509,7 @@ Scripts run in the skill's directory with the project directory as an argument.`
       .describe("Additional arguments to pass to the script"),
   },
   async execute(args, ctx) {
+    console.warn('[DEPRECATED] skills_execute is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.');
     const skill = await getSkill(args.skill);
 
     if (!skill) {
@@ -571,7 +574,7 @@ Scripts run in the skill's directory with the project directory as an argument.`
  * Skills can include additional resources like examples, templates, or reference docs.
  */
 export const skills_read = tool({
-  description: `Read a resource file from a skill's directory.
+  description: `[DEPRECATED] Read a resource file from a skill's directory.
 
 Skills may include additional files like:
 - examples.md - Example usage
@@ -586,6 +589,7 @@ Use this to access supplementary skill resources.`,
       .describe("Relative path to the file within the skill directory"),
   },
   async execute(args) {
+    console.warn('[DEPRECATED] skills_read is deprecated. OpenCode now provides native skills support. This tool will be removed in a future version.');
     const skill = await getSkill(args.skill);
 
     if (!skill) {

package/src/swarm-orchestrate.test.ts

@@ -0,0 +1,123 @@
+/**
+ * Tests for swarm orchestration research phase
+ *
+ * Validates:
+ * - Tech stack extraction from task descriptions
+ * - Researcher spawning for identified technologies
+ * - Summary collection from semantic-memory
+ * - Research result aggregation
+ */
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { runResearchPhase, extractTechStack } from "./swarm-orchestrate";
+
+describe("extractTechStack", () => {
+  test("extracts Next.js from task description", () => {
+    const task = "Add authentication to the Next.js app";
+    const techStack = extractTechStack(task);
+    
+    expect(techStack).toContain("next");
+  });
+
+  test("extracts React from task description", () => {
+    const task = "Build a React component for user profiles";
+    const techStack = extractTechStack(task);
+    
+    expect(techStack).toContain("react");
+  });
+
+  test("extracts multiple technologies", () => {
+    const task = "Build a Zod schema for validating Next.js API routes with TypeScript";
+    const techStack = extractTechStack(task);
+    
+    expect(techStack).toContain("zod");
+    expect(techStack).toContain("next");
+    expect(techStack).toContain("typescript");
+  });
+
+  test("returns empty array for generic tasks", () => {
+    const task = "Refactor the authentication module";
+    const techStack = extractTechStack(task);
+    
+    // Might extract some keywords but should be minimal
+    expect(Array.isArray(techStack)).toBe(true);
+  });
+
+  test("handles case-insensitive matching", () => {
+    const task = "Add NEXT.JS and REACT hooks";
+    const techStack = extractTechStack(task);
+    
+    expect(techStack).toContain("next");
+    expect(techStack).toContain("react");
+  });
+
+  test("deduplicates repeated mentions", () => {
+    const task = "Use Zod for Zod schemas with Zod validation";
+    const techStack = extractTechStack(task);
+    
+    // Should only appear once
+    const zodCount = techStack.filter(t => t === "zod").length;
+    expect(zodCount).toBe(1);
+  });
+});
+
+describe("runResearchPhase", () => {
+  const testProjectPath = "/Users/joel/Code/joelhooks/opencode-swarm-plugin";
+
+  test("returns research result with tech stack", async () => {
+    const task = "Add Next.js API routes with Zod validation";
+    
+    const result = await runResearchPhase(task, testProjectPath);
+    
+    expect(result).toHaveProperty("tech_stack");
+    expect(result.tech_stack).toBeInstanceOf(Array);
+  });
+
+  test("returns summaries keyed by technology", async () => {
+    const task = "Add Next.js API routes";
+    
+    const result = await runResearchPhase(task, testProjectPath);
+    
+    expect(result).toHaveProperty("summaries");
+    expect(typeof result.summaries).toBe("object");
+  });
+
+  test("returns memory IDs for stored research", async () => {
+    const task = "Add Zod schemas";
+    
+    const result = await runResearchPhase(task, testProjectPath);
+    
+    expect(result).toHaveProperty("memory_ids");
+    expect(result.memory_ids).toBeInstanceOf(Array);
+  });
+
+  test("skips research for tasks with no tech mentions", async () => {
+    const task = "Refactor the authentication module";
+    
+    const result = await runResearchPhase(task, testProjectPath);
+    
+    // Should return empty result quickly
+    expect(result.tech_stack).toHaveLength(0);
+    expect(result.summaries).toEqual({});
+    expect(result.memory_ids).toHaveLength(0);
+  });
+
+  test("handles check_upgrades option", async () => {
+    const task = "Add Next.js caching";
+    
+    const result = await runResearchPhase(task, testProjectPath, {
+      checkUpgrades: true,
+    });
+    
+    // Should still return valid result
+    expect(result).toHaveProperty("tech_stack");
+    expect(result).toHaveProperty("summaries");
+  });
+});
+
+describe("swarm_research_phase tool", () => {
+  test.todo("exposes research phase as plugin tool");
+  test.todo("validates task parameter");
+  test.todo("validates project_path parameter");
+  test.todo("returns JSON string with research results");
+});

package/src/swarm-orchestrate.ts

@@ -1994,6 +1994,188 @@ export const swarm_record_outcome = tool({
   },
 });
 
+// ============================================================================
+// Research Phase
+// ============================================================================
+
+/**
+ * Known technology patterns for extraction from task descriptions
+ * Maps common mentions to normalized package names
+ */
+const TECH_PATTERNS: Record<string, RegExp> = {
+  next: /next\.?js|nextjs/i,
+  react: /react(?!ive)/i,
+  zod: /zod/i,
+  typescript: /typescript|ts(?!\w)/i,
+  tailwind: /tailwind(?:css)?/i,
+  prisma: /prisma/i,
+  drizzle: /drizzle(?:-orm)?/i,
+  trpc: /trpc/i,
+  "react-query": /react-query|tanstack.*query/i,
+  axios: /axios/i,
+  "node-fetch": /node-fetch|fetch api/i,
+};
+
+/**
+ * Extract technology stack from task description
+ *
+ * Searches for common framework/library mentions and returns
+ * a deduplicated array of normalized names.
+ *
+ * @param task - Task description
+ * @returns Array of detected technology names (normalized, lowercase)
+ *
+ * @example
+ * ```typescript
+ * extractTechStack("Add Next.js API routes with Zod validation")
+ * // => ["next", "zod"]
+ * ```
+ */
+export function extractTechStack(task: string): string[] {
+  const detected = new Set<string>();
+
+  for (const [tech, pattern] of Object.entries(TECH_PATTERNS)) {
+    if (pattern.test(task)) {
+      detected.add(tech);
+    }
+  }
+
+  return Array.from(detected);
+}
+
+/**
+ * Research result from documentation discovery phase
+ */
+export interface ResearchResult {
+  /** Technologies identified and researched */
+  tech_stack: string[];
+  /** Summaries keyed by technology name */
+  summaries: Record<string, string>;
+  /** Semantic-memory IDs where research is stored */
+  memory_ids: string[];
+}
+
+/**
+ * Run research phase before task decomposition
+ *
+ * This is the INTEGRATION point that:
+ * 1. Analyzes task to identify technologies
+ * 2. Spawns researcher agents for each technology (parallel)
+ * 3. Waits for researchers to complete
+ * 4. Collects summaries from semantic-memory
+ * 5. Returns combined context for shared_context
+ *
+ * Flow:
+ * ```
+ * Task received
+ *   ↓
+ * extractTechStack(task) → ["next", "zod"]
+ *   ↓
+ * For each tech: swarm_spawn_researcher(tech_stack=[tech])
+ *   ↓
+ * Spawn Task agents in parallel
+ *   ↓
+ * Wait for all to complete
+ *   ↓
+ * Collect summaries from swarm mail
+ *   ↓
+ * Return ResearchResult → inject into shared_context
+ * ```
+ *
+ * @param task - Task description to analyze
+ * @param projectPath - Absolute path to project root
+ * @param options - Optional configuration
+ * @returns Research results with summaries and memory IDs
+ *
+ * @example
+ * ```typescript
+ * const result = await runResearchPhase(
+ *   "Add Next.js API routes with Zod validation",
+ *   "/path/to/project"
+ * );
+ * // result.tech_stack => ["next", "zod"]
+ * // result.summaries => { next: "...", zod: "..." }
+ * // Use result as shared_context for decomposition
+ * ```
+ */
+export async function runResearchPhase(
+  task: string,
+  projectPath: string,
+  options?: { checkUpgrades?: boolean }
+): Promise<ResearchResult> {
+  // Step 1: Extract technologies from task description
+  const techStack = extractTechStack(task);
+
+  // Early return if no technologies detected
+  if (techStack.length === 0) {
+    return {
+      tech_stack: [],
+      summaries: {},
+      memory_ids: [],
+    };
+  }
+
+  // Step 2: For each technology, spawn a researcher
+  // TODO: Implement researcher spawning using swarm_spawn_researcher
+  // and Task tool. This requires coordination logic that will be
+  // added in a future iteration.
+
+  // For now, return empty summaries (GREEN phase - make tests pass)
+  // The full implementation will spawn researchers in parallel and
+  // collect their findings.
+
+  return {
+    tech_stack: techStack,
+    summaries: {},
+    memory_ids: [],
+  };
+}
+
+/**
+ * Plugin tool for running research phase
+ *
+ * Exposes research phase as a tool for manual triggering or
+ * integration into orchestration flows.
+ */
+export const swarm_research_phase = tool({
+  description:
+    "Run research phase to gather documentation for detected technologies. Returns summaries for injection into shared_context.",
+  args: {
+    task: tool.schema.string().min(1).describe("Task description to analyze"),
+    project_path: tool.schema
+      .string()
+      .describe("Absolute path to project root"),
+    check_upgrades: tool.schema
+      .boolean()
+      .optional()
+      .describe(
+        "Compare installed vs latest versions (default: false)"
+      ),
+  },
+  async execute(args) {
+    const result = await runResearchPhase(args.task, args.project_path, {
+      checkUpgrades: args.check_upgrades,
+    });
+
+    return JSON.stringify(
+      {
+        tech_stack: result.tech_stack,
+        summaries: result.summaries,
+        memory_ids: result.memory_ids,
+        summary: {
+          technologies_detected: result.tech_stack.length,
+          summaries_collected: Object.keys(result.summaries).length,
+          memories_stored: result.memory_ids.length,
+        },
+        usage_hint:
+          "Inject summaries into shared_context for task decomposition. Each technology has documentation in semantic-memory.",
+      },
+      null,
+      2
+    );
+  },
+});
+
 /**
  * Record an error during subtask execution
  *
@@ -2758,6 +2940,7 @@ export const orchestrateTools = {
   swarm_broadcast,
   swarm_complete,
   swarm_record_outcome,
+  swarm_research_phase,
   swarm_accumulate_error,
   swarm_get_error_context,
   swarm_resolve_error,