@studio-foundation/runner 0.3.0-beta.1

package/src/plugins/plugin-loader.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadPlugins } from './plugin-loader.js';
+
+let tmpDir: string;
+
+beforeAll(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'studio-plugin-test-'));
+
+  // Plugin 1: code-review — has .mcp.json + skills
+  const plugin1 = join(tmpDir, 'code-review');
+  await mkdir(join(plugin1, 'skills'), { recursive: true });
+  await writeFile(
+    join(plugin1, '.mcp.json'),
+    JSON.stringify({
+      mcpServers: {
+        github: { command: 'npx', args: ['-y', '@mcp/server-github'] },
+      },
+    })
+  );
+  await writeFile(
+    join(plugin1, 'skills', 'review-guidelines.skill.md'),
+    '# Review Guidelines\n\nAlways check for security issues.'
+  );
+  await writeFile(
+    join(plugin1, 'skills', 'security-checklist.skill.md'),
+    '# Security Checklist\n\n- Check SQL injection\n- Check XSS'
+  );
+
+  // Plugin 2: analysis — skills only, no .mcp.json
+  const plugin2 = join(tmpDir, 'analysis');
+  await mkdir(join(plugin2, 'skills'), { recursive: true });
+  await writeFile(
+    join(plugin2, 'skills', 'analysis-tips.skill.md'),
+    '# Analysis Tips\n\nBe thorough.'
+  );
+
+  // Plugin 3: empty — no .mcp.json, no skills
+  await mkdir(join(tmpDir, 'empty-plugin'));
+
+  // Plugin 4: flat-plugin — flat .mcp.json (Claude Code format, no mcpServers wrapper)
+  const plugin4 = join(tmpDir, 'flat-plugin');
+  await mkdir(plugin4, { recursive: true });
+  await writeFile(
+    join(plugin4, '.mcp.json'),
+    JSON.stringify({
+      context7: { command: 'npx', args: ['-y', '@upstash/context7-mcp'] },
+    })
+  );
+});
+
+afterAll(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+describe('loadPlugins', () => {
+  it('returns empty array when plugins dir does not exist', async () => {
+    const result = await loadPlugins('/nonexistent/path/to/plugins');
+    expect(result).toEqual([]);
+  });
+
+  it('loads all plugin directories', async () => {
+    const result = await loadPlugins(tmpDir);
+    expect(result).toHaveLength(4);
+    const names = result.map((p) => p.name).sort();
+    expect(names).toEqual(['analysis', 'code-review', 'empty-plugin', 'flat-plugin']);
+  });
+
+  it('parses .mcp.json into mcpServers', async () => {
+    const result = await loadPlugins(tmpDir);
+    const codeReview = result.find((p) => p.name === 'code-review')!;
+    expect(codeReview.mcpServers).toEqual({
+      github: { command: 'npx', args: ['-y', '@mcp/server-github'] },
+    });
+  });
+
+  it('sets mcpServers to empty object when no .mcp.json', async () => {
+    const result = await loadPlugins(tmpDir);
+    const analysis = result.find((p) => p.name === 'analysis')!;
+    expect(analysis.mcpServers).toEqual({});
+  });
+
+  it('loads skill files sorted by name', async () => {
+    const result = await loadPlugins(tmpDir);
+    const codeReview = result.find((p) => p.name === 'code-review')!;
+    expect(codeReview.skills).toHaveLength(2);
+    expect(codeReview.skills[0].name).toBe('review-guidelines');
+    expect(codeReview.skills[0].content).toContain('Review Guidelines');
+    expect(codeReview.skills[1].name).toBe('security-checklist');
+  });
+
+  it('returns empty skills array when no skills dir', async () => {
+    const result = await loadPlugins(tmpDir);
+    const empty = result.find((p) => p.name === 'empty-plugin')!;
+    expect(empty.skills).toEqual([]);
+    expect(empty.mcpServers).toEqual({});
+  });
+
+  it('sets path to absolute path of plugin directory', async () => {
+    const result = await loadPlugins(tmpDir);
+    const codeReview = result.find((p) => p.name === 'code-review')!;
+    expect(codeReview.path).toBe(join(tmpDir, 'code-review'));
+  });
+
+  it('parses flat .mcp.json without mcpServers wrapper — Claude Code format', async () => {
+    const result = await loadPlugins(tmpDir);
+    const flatPlugin = result.find((p) => p.name === 'flat-plugin')!;
+    expect(flatPlugin.mcpServers).toEqual({
+      context7: { command: 'npx', args: ['-y', '@upstash/context7-mcp'] },
+    });
+  });
+});

package/src/plugins/plugin-loader.ts

@@ -0,0 +1,90 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+export type MCPServerDef =
+  | { type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string> }
+  | {
+      type: 'http';
+      url: string;
+      headers?: Record<string, string>;
+      env?: Record<string, string>;
+      auth?: { type: 'oauth'; client_id?: string; client_secret?: string; scope?: string };
+    };
+
+export interface SkillContent {
+  name: string;    // filename without .skill.md
+  content: string; // markdown content
+}
+
+export interface PluginManifest {
+  name: string;
+  path: string;
+  mcpServers: Record<string, MCPServerDef>;
+  skills: SkillContent[];
+}
+
+export async function loadPlugins(pluginsDir: string): Promise<PluginManifest[]> {
+  if (!existsSync(pluginsDir)) return [];
+
+  let entries: import('node:fs').Dirent[];
+  try {
+    entries = await readdir(pluginsDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const manifests: PluginManifest[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const pluginPath = join(pluginsDir, entry.name);
+    manifests.push(await loadPlugin(entry.name, pluginPath));
+  }
+  return manifests;
+}
+
+async function loadPlugin(name: string, pluginPath: string): Promise<PluginManifest> {
+  const mcpPath = join(pluginPath, '.mcp.json');
+  let mcpServers: Record<string, MCPServerDef> = {};
+  if (existsSync(mcpPath)) {
+    try {
+      const raw = await readFile(mcpPath, 'utf-8');
+      const parsed = JSON.parse(raw) as Record<string, unknown>;
+      // Support both .mcp.json formats:
+      // 1. Wrapped Studio format: { "mcpServers": { "serverName": { ... } } }
+      // 2. Flat Claude Code format: { "serverName": { ... } }
+      // This ensures compatibility with both Studio MCP configurations and
+      // plugins from the Claude Code sandbox that use the flat format.
+      // Fixes STU-122: Plugin loader should support both .mcp.json formats
+      if ('mcpServers' in parsed && parsed.mcpServers !== null && typeof parsed.mcpServers === 'object') {
+        mcpServers = parsed.mcpServers as Record<string, MCPServerDef>;
+      } else {
+        mcpServers = parsed as Record<string, MCPServerDef>;
+      }
+    } catch {
+      // Malformed .mcp.json — skip silently
+    }
+  }
+
+  const skills = await loadSkillFiles(join(pluginPath, 'skills'));
+  return { name, path: pluginPath, mcpServers, skills };
+}
+
+async function loadSkillFiles(skillsDir: string): Promise<SkillContent[]> {
+  if (!existsSync(skillsDir)) return [];
+
+  let files: string[];
+  try {
+    files = await readdir(skillsDir);
+  } catch {
+    return [];
+  }
+
+  const skillFiles = files.filter((f) => f.endsWith('.skill.md')).sort();
+  const skills: SkillContent[] = [];
+  for (const file of skillFiles) {
+    const content = await readFile(join(skillsDir, file), 'utf-8');
+    skills.push({ name: basename(file, '.skill.md'), content });
+  }
+  return skills;
+}

package/src/prompt-builder.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest';
+import { buildPrompt } from './prompt-builder.js';
+import type { AgentConfig } from '@studio-foundation/contracts';
+import type { SkillContent } from './tools/skills/skill-loader.js';
+
+const AGENT: AgentConfig = {
+  name: 'test-agent',
+  provider: 'anthropic',
+  model: 'claude-haiku-4-5-20251001',
+  system_prompt: 'You are a helpful assistant.',
+};
+
+const TASK = { description: 'Do the thing.' };
+
+describe('buildPrompt — previous_tool_results', () => {
+  it('renders write_file content from tc.arguments.content', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: {
+        previous_tool_results: {
+          'code-generation': [
+            {
+              id: '1',
+              name: 'repo_manager-write_file',
+              arguments: { path: 'src/foo.ts', content: 'const x = 1;' },
+              result: { written: true },
+            },
+          ],
+        },
+      },
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).toContain('Previous Stage Discoveries (code-generation)');
+    expect(userMsg).toContain('const x = 1;');
+    // Should NOT show the useless {written: true} result as the body
+    expect(userMsg).not.toContain('"written": true');
+  });
+
+  it('renders read_file content from tc.result', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: {
+        previous_tool_results: {
+          'brief-analysis': [
+            {
+              id: '1',
+              name: 'repo_manager-read_file',
+              arguments: { path: 'src/foo.ts' },
+              result: { path: 'src/foo.ts', content: 'const y = 2;' },
+            },
+          ],
+        },
+      },
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).toContain('Previous Stage Discoveries (brief-analysis)');
+    expect(userMsg).toContain('const y = 2;');
+  });
+
+  it('omits the section when previous_tool_results is absent', () => {
+    const messages = buildPrompt({ agent: AGENT, task: TASK, context: {} });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).not.toContain('Previous Stage Discoveries');
+  });
+});
+
+describe('buildPrompt — startup_context', () => {
+  it('renders each startup_context key as a ### section under ## Pipeline Startup Context', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: {
+        startup_context: {
+          git_status: 'M src/foo.ts',
+          recent_commits: 'abc123 feat: stuff',
+        },
+      },
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).toContain('## Pipeline Startup Context');
+    expect(userMsg).toContain('### git_status');
+    expect(userMsg).toContain('M src/foo.ts');
+    expect(userMsg).toContain('### recent_commits');
+    expect(userMsg).toContain('abc123 feat: stuff');
+  });
+
+  it('omits the section when startup_context is absent', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: {},
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).not.toContain('Pipeline Startup Context');
+  });
+
+  it('omits the section when startup_context is empty', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: { startup_context: {} },
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).not.toContain('Pipeline Startup Context');
+  });
+});
+
+describe('buildPrompt — skills injection', () => {
+  it('injects a single skill into the system prompt', () => {
+    const skills: SkillContent[] = [
+      { name: 'commit-conventions', content: '# Commit Conventions\n\nUse conventional commits.' },
+    ];
+    const messages = buildPrompt({ agent: AGENT, task: TASK, context: {}, skills });
+    const sysMsg = messages.find(m => m.role === 'system')!.content as string;
+    expect(sysMsg).toContain('## Skill: commit-conventions');
+    expect(sysMsg).toContain('Use conventional commits.');
+  });
+
+  it('injects multiple skills separated by ---', () => {
+    const skills: SkillContent[] = [
+      { name: 'commit-conventions', content: 'Commit content.' },
+      { name: 'react-patterns', content: 'React content.' },
+    ];
+    const messages = buildPrompt({ agent: AGENT, task: TASK, context: {}, skills });
+    const sysMsg = messages.find(m => m.role === 'system')!.content as string;
+    expect(sysMsg).toContain('## Skill: commit-conventions');
+    expect(sysMsg).toContain('## Skill: react-patterns');
+    expect(sysMsg).toContain('---');
+  });
+
+  it('omits skill section when skills array is empty', () => {
+    const messages = buildPrompt({ agent: AGENT, task: TASK, context: {}, skills: [] });
+    const sysMsg = messages.find(m => m.role === 'system')!.content as string;
+    expect(sysMsg).not.toContain('## Skill:');
+  });
+
+  it('omits skill section when skills is not provided', () => {
+    const messages = buildPrompt({ agent: AGENT, task: TASK, context: {} });
+    const sysMsg = messages.find(m => m.role === 'system')!.content as string;
+    expect(sysMsg).not.toContain('## Skill:');
+  });
+});
+
+describe('buildPrompt — stage_name', () => {
+  it('renders ## Stage Name section when stage_name is provided', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: { stage_name: 'recipe-1' },
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).toContain('## Stage Name');
+    expect(userMsg).toContain('recipe-1');
+  });
+
+  it('does not render ## Stage Name when stage_name is absent', () => {
+    const messages = buildPrompt({
+      agent: AGENT,
+      task: TASK,
+      context: {},
+    });
+    const userMsg = messages.find(m => m.role === 'user')!.content as string;
+    expect(userMsg).not.toContain('## Stage Name');
+  });
+});