@studio-foundation/runner 0.3.0-beta.1 → 0.3.0-beta.6

package/src/tools/tool-registry.ts

@@ -1,130 +0,0 @@
-/**
- * Tool registry - manages tool definitions and execution
- */
-
-import { ToolDefinition } from '@studio-foundation/contracts';
-
-/** Normalize tool name: dots → hyphens so both conventions work */
-export function normalizeToolName(name: string): string {
-  return name.replace(/\./g, '-');
-}
-
-export interface ToolResult {
-  success: boolean;
-  output: unknown;
-  error?: string;
-}
-
-export interface Tool {
-  name: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  execute(args: Record<string, unknown>): Promise<ToolResult>;
-}
-
-export class ToolRegistry {
-  private tools: Map<string, Tool> = new Map();
-  private toolToPlugin: Map<string, string> = new Map();   // normalized name → plugin name
-  private pluginSnippets: Map<string, string> = new Map(); // plugin name → snippet
-
-  /**
-   * Register a single tool (no plugin metadata).
-   */
-  register(tool: Tool): void {
-    this.tools.set(tool.name, tool);
-  }
-
-  /**
-   * Register all tools belonging to a plugin.
-   * If promptSnippet is provided it will be returned by getActiveSnippets()
-   * whenever any tool from this plugin is in the registry.
-   */
-  registerPlugin(pluginName: string, tools: Tool[], promptSnippet?: string): void {
-    for (const tool of tools) {
-      this.register(tool);
-      this.toolToPlugin.set(normalizeToolName(tool.name), pluginName);
-    }
-    if (promptSnippet) {
-      this.pluginSnippets.set(pluginName, promptSnippet);
-    }
-  }
-
-  /**
-   * Get tool by name
-   */
-  get(name: string): Tool | undefined {
-    return this.tools.get(name);
-  }
-
-  /**
-   * Check if tool exists
-   */
-  has(name: string): boolean {
-    return this.tools.has(name);
-  }
-
-  /**
-   * List all tools
-   */
-  list(): Tool[] {
-    return Array.from(this.tools.values());
-  }
-
-  /**
-   * Convert tools to LLM tool definitions format
-   */
-  toToolDefinitions(): ToolDefinition[] {
-    return this.list().map(tool => ({
-      name: tool.name,
-      description: tool.description,
-      parameters: tool.parameters
-    }));
-  }
-
-  /**
-   * Return prompt snippets for all plugins that have at least one tool
-   * currently in this registry.
-   */
-  getActiveSnippets(): string[] {
-    const activePlugins = new Set<string>();
-    for (const toolName of this.tools.keys()) {
-      const plugin = this.toolToPlugin.get(normalizeToolName(toolName));
-      if (plugin) activePlugins.add(plugin);
-    }
-    return Array.from(activePlugins)
-      .map(p => this.pluginSnippets.get(p))
-      .filter((s): s is string => s !== undefined);
-  }
-
-  /**
-   * Create a new registry filtered to specific tool names.
-   * Normalizes dots to hyphens so both "repo_manager.write_file"
-   * and "repo_manager-write_file" match the registered name.
-   * Plugin snippet metadata is carried over for included tools.
-   */
-  filter(allowedTools: string[]): ToolRegistry {
-    const filtered = new ToolRegistry();
-    for (const toolName of allowedTools) {
-      const tool = this.tools.get(toolName)
-        ?? this.tools.get(normalizeToolName(toolName));
-      if (tool) {
-        filtered.register(tool);
-        // Carry over plugin metadata so getActiveSnippets() works on filtered registry
-        const pluginName = this.toolToPlugin.get(normalizeToolName(tool.name));
-        if (pluginName) {
-          filtered.toolToPlugin.set(normalizeToolName(tool.name), pluginName);
-          const snippet = this.pluginSnippets.get(pluginName);
-          if (snippet) filtered.pluginSnippets.set(pluginName, snippet);
-        }
-      }
-    }
-    return filtered;
-  }
-
-  /**
-   * Create a full copy of this registry (all tools + plugin metadata).
-   */
-  clone(): ToolRegistry {
-    return this.filter(Array.from(this.tools.keys()));
-  }
-}

package/src/tools/yaml-executor.ts

@@ -1,120 +0,0 @@
-// runner/src/tools/yaml-executor.ts
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-import type { ParseOutputFormat } from '@studio-foundation/contracts';
-
-const execFileAsync = promisify(execFile);
-
-/**
- * Render a shell command template with parameter substitution.
- *
- * Supports:
- *   {{param}}              → stringify value (empty string if undefined)
- *   {{#if param}}...{{/if}}              → include block only when param is truthy
- *   {{#if param}}...{{else}}...{{/if}}   → if/else block
- *   {{param | join 'sep'}} → join array with separator
- *   {{param | json}}       → JSON.stringify(value)
- */
-export function renderTemplate(
-  template: string,
-  params: Record<string, unknown>
-): string {
-  let result = template;
-
-  // {{#if param}}...{{else}}...{{/if}} blocks (with else)
-  result = result.replace(
-    /\{\{#if (\w+)\}\}([\s\S]*?)\{\{else\}\}([\s\S]*?)\{\{\/if\}\}/g,
-    (_, key: string, trueBranch: string, falseBranch: string) =>
-      params[key] ? trueBranch : falseBranch
-  );
-
-  // {{#if param}}...{{/if}} blocks (without else)
-  result = result.replace(
-    /\{\{#if (\w+)\}\}([\s\S]*?)\{\{\/if\}\}/g,
-    (_, key: string, inner: string) => (params[key] ? inner : '')
-  );
-
-  // {{param | join 'sep'}} filter
-  result = result.replace(
-    /\{\{(\w+)\s*\|\s*join\s+'([^']*)'\}\}/g,
-    (_, key: string, sep: string) => {
-      const value = params[key];
-      return Array.isArray(value) ? value.join(sep) : String(value ?? '');
-    }
-  );
-
-  // {{param | join "sep"}} filter (double quotes variant)
-  result = result.replace(
-    /\{\{(\w+)\s*\|\s*join\s+"([^"]*)"\}\}/g,
-    (_, key: string, sep: string) => {
-      const value = params[key];
-      return Array.isArray(value) ? value.join(sep) : String(value ?? '');
-    }
-  );
-
-  // {{param | json}} filter
-  result = result.replace(
-    /\{\{(\w+)\s*\|\s*json\}\}/g,
-    (_, key: string) => JSON.stringify(params[key] ?? null)
-  );
-
-  // Plain {{param}} substitution
-  result = result.replace(
-    /\{\{(\w+)\}\}/g,
-    (_, key: string) => (params[key] === undefined ? '' : String(params[key]))
-  );
-
-  return result;
-}
-
-export interface ShellResult {
-  success: boolean;
-  output: unknown;
-  error?: string;
-}
-
-/**
- * Execute a rendered shell command and parse the output.
- */
-export async function executeShellCommand(
-  command: string,
-  parseOutput: ParseOutputFormat = 'text',
-  workingDir: string,
-  timeoutMs: number = 30_000,
-  env?: Record<string, string>
-): Promise<ShellResult> {
-  try {
-    const { stdout } = await execFileAsync('sh', ['-c', command], {
-      cwd: workingDir,
-      timeout: timeoutMs,
-      maxBuffer: 10 * 1024 * 1024,
-      ...(env ? { env: { ...process.env, ...env } } : {}),
-    });
-
-    const raw = stdout.trim();
-
-    if (parseOutput === 'json') {
-      try {
-        return { success: true, output: JSON.parse(raw) };
-      } catch {
-        return {
-          success: false,
-          output: undefined,
-          error: `Failed to parse JSON output: ${raw.slice(0, 200)}`,
-        };
-      }
-    }
-
-    return { success: true, output: raw };
-  } catch (err: unknown) {
-    const e = err as { message?: string; stderr?: string; stdout?: string };
-    // When claude -p exits non-zero, the JSON result is still in stdout.
-    // Try to parse it so the runner gets structured error info instead of "Command failed".
-    if (parseOutput === 'json' && e.stdout?.trim()) {
-      try {
-        return { success: false, output: JSON.parse(e.stdout.trim()), error: e.stderr?.trim() || undefined };
-      } catch { /* fall through to default error */ }
-    }
-    return { success: false, output: undefined, error: e.stderr?.trim() || e.message || 'Command failed' };
-  }
-}

package/src/utils/race-signal.test.ts

@@ -1,50 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { raceSignal } from './race-signal.js';
-
-describe('raceSignal', () => {
-  it('resolves normally when no signal provided', async () => {
-    const result = await raceSignal(Promise.resolve(42));
-    expect(result).toBe(42);
-  });
-
-  it('resolves normally when signal is not aborted', async () => {
-    const controller = new AbortController();
-    const result = await raceSignal(Promise.resolve('hello'), controller.signal);
-    expect(result).toBe('hello');
-  });
-
-  it('rejects immediately if signal is already aborted', async () => {
-    const controller = new AbortController();
-    controller.abort();
-    await expect(raceSignal(new Promise(() => {}), controller.signal))
-      .rejects.toThrow('Aborted');
-  });
-
-  it('rejects when signal fires after creation', async () => {
-    const controller = new AbortController();
-    // A promise that never resolves on its own
-    const hanging = new Promise<never>(() => {});
-    const raced = raceSignal(hanging, controller.signal);
-    controller.abort();
-    await expect(raced).rejects.toThrow('Aborted');
-  });
-
-  it('resolves if promise resolves before signal fires', async () => {
-    const controller = new AbortController();
-    const result = await raceSignal(Promise.resolve(99), controller.signal);
-    // Abort after the fact — should not cause rejection
-    controller.abort();
-    expect(result).toBe(99);
-  });
-
-  it('thrown error name is AbortError', async () => {
-    const controller = new AbortController();
-    controller.abort();
-    try {
-      await raceSignal(new Promise(() => {}), controller.signal);
-    } catch (e) {
-      expect(e).toBeInstanceOf(DOMException);
-      expect((e as DOMException).name).toBe('AbortError');
-    }
-  });
-});

package/src/utils/race-signal.ts

@@ -1,17 +0,0 @@
-/**
- * Race a promise against an AbortSignal.
- * Rejects with DOMException('Aborted', 'AbortError') if the signal fires first.
- */
-export function raceSignal<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(new DOMException('Aborted', 'AbortError'));
-
-  return new Promise((resolve, reject) => {
-    const onAbort = () => reject(new DOMException('Aborted', 'AbortError'));
-    signal.addEventListener('abort', onAbort, { once: true });
-
-    promise
-      .then((v) => { signal.removeEventListener('abort', onAbort); resolve(v); })
-      .catch((e) => { signal.removeEventListener('abort', onAbort); reject(e); });
-  });
-}

package/templates/integrations/linear.integration.yaml

@@ -1,35 +0,0 @@
-name: linear
-version: 1
-description: "Linear webhook trigger + issue status sync"
-
-config:
-  required:
-    - LINEAR_API_KEY
-    - LINEAR_WEBHOOK_SECRET
-  optional:
-    autoTrigger: false
-
-webhook:
-  hmac:
-    header: linear-signature
-    secret_env: LINEAR_WEBHOOK_SECRET
-  handler: linear-webhook
-
-on_failure:
-  handler: linear-failure
-
-events:
-  consumes:
-    - linear.issue.in_progress
-  emits:
-    - pipeline.complete
-    - pipeline.failed
-
-test:
-  type: http
-  endpoint: https://api.linear.app/graphql
-  method: POST
-  auth: bearer:${LINEAR_API_KEY}
-  body: '{"query":"{ viewer { id name } }"}'
-  expect:
-    status: 200

package/templates/integrations/slack.integration.yaml

@@ -1,22 +0,0 @@
-name: slack
-version: 1
-description: "Slack notifications for pipeline events"
-
-config:
-  required:
-    - SLACK_BOT_TOKEN
-  optional:
-    channel: "#studio-runs"
-
-events:
-  emits:
-    - pipeline.complete
-    - pipeline.failed
-
-test:
-  type: http
-  endpoint: https://slack.com/api/auth.test
-  method: POST
-  auth: bearer:${SLACK_BOT_TOKEN}
-  expect:
-    status: 200

package/templates/integrations/webhook.integration.yaml

@@ -1,17 +0,0 @@
-name: webhook
-version: 1
-description: "Generic HTTP webhook notifications for pipeline events"
-
-config:
-  optional:
-    url: ""
-    events: "pipeline.complete,pipeline.failed"
-    secret: ""
-
-events:
-  emits:
-    - pipeline.complete
-    - pipeline.failed
-    - pipeline.start
-    - stage.complete
-    - stage.failed

package/templates/tools/git.tool.yaml

@@ -1,80 +0,0 @@
-name: git
-description: Git version control operations
-version: 1
-
-commands:
-  - name: git-status
-    description: Show working tree status
-    parameters: {}
-    execute:
-      type: shell
-      command: git status --porcelain
-      parse_output: text
-
-  - name: git-diff
-    description: Show changes in the working tree
-    parameters:
-      staged:
-        type: boolean
-        required: false
-        description: Show staged changes instead of unstaged
-      file:
-        type: string
-        required: false
-        description: Restrict diff to this file path
-    execute:
-      type: shell
-      command: |
-        git diff {{#if staged}}--cached{{/if}} {{#if file}}{{file}}{{/if}}
-      parse_output: text
-
-  - name: git-checkout
-    description: Checkout an existing branch or create a new one
-    parameters:
-      branch:
-        type: string
-        required: true
-        description: Branch name to checkout or create
-      create:
-        type: boolean
-        required: false
-        description: Create the branch if it does not exist
-    execute:
-      type: shell
-      command: |
-        git checkout {{#if create}}-b{{/if}} {{branch}}
-      parse_output: text
-
-  - name: git-commit
-    description: Stage all changes and commit with a message
-    parameters:
-      message:
-        type: string
-        required: true
-        description: Commit message (use conventional commits format)
-    execute:
-      type: shell
-      command: |
-        git add -A && git commit -m "{{message}}"
-      parse_output: text
-
-  - name: git-push
-    description: Push the current branch to origin
-    parameters:
-      set_upstream:
-        type: boolean
-        required: false
-        description: Set upstream tracking reference (-u flag)
-    execute:
-      type: shell
-      command: |
-        git push {{#if set_upstream}}-u{{/if}} origin HEAD
-      parse_output: text
-
-prompt_snippet: |
-  You have access to git tools. Always create a feature branch before making changes.
-  Never commit directly to main or master.
-  Use conventional commit messages: <type>(<scope>): <description>
-
-constraints:
-  requires_binaries: [git]

package/templates/tools/repo-manager.tool.yaml

@@ -1,64 +0,0 @@
-name: repo_manager
-description: Read and write files in the workspace
-version: 1
-
-commands:
-  - name: repo_manager-read_file
-    description: Read a file from the workspace
-    parameters:
-      path:
-        type: string
-        required: true
-        description: File path relative to the workspace root
-    execute:
-      type: builtin
-      parse_output: json
-
-  - name: repo_manager-write_file
-    description: Write or create a file in the workspace
-    parameters:
-      path:
-        type: string
-        required: true
-        description: File path relative to the workspace root
-      content:
-        type: string
-        required: true
-        description: Full content to write to the file
-    execute:
-      type: builtin
-      parse_output: json
-
-  - name: repo_manager-list_files
-    description: List files in the workspace
-    parameters:
-      path:
-        type: string
-        required: false
-        description: Directory to list (default is workspace root)
-      recursive:
-        type: boolean
-        required: false
-        description: Whether to list recursively
-    execute:
-      type: builtin
-      parse_output: json
-
-  - name: repo_manager-apply_patch
-    description: Apply a unified diff patch to a file
-    parameters:
-      path:
-        type: string
-        required: true
-        description: File path to patch
-      patch:
-        type: string
-        required: true
-        description: Unified diff patch content
-    execute:
-      type: builtin
-      parse_output: json
-
-prompt_snippet: |
-  You have access to file management tools. Read files before modifying them.
-  Use repo_manager-write_file to create or update files — provide the full file content.

package/templates/tools/search.tool.yaml

@@ -1,22 +0,0 @@
-name: search
-description: Search the codebase by content or file pattern
-version: 1
-
-commands:
-  - name: search-search_codebase
-    description: Search files by content pattern (uses ripgrep)
-    parameters:
-      pattern:
-        type: string
-        required: true
-        description: Regex or literal pattern to search for
-      file_pattern:
-        type: string
-        required: false
-        description: Glob pattern to restrict which files are searched (e.g. "*.ts")
-    execute:
-      type: builtin
-      parse_output: json
-
-prompt_snippet: |
-  You have access to a codebase search tool. Use it to find relevant code before making changes.

package/templates/tools/shell.tool.yaml

@@ -1,19 +0,0 @@
-name: shell
-description: Execute shell commands in the workspace
-version: 1
-
-commands:
-  - name: shell-run_command
-    description: Run a shell command in the workspace directory
-    parameters:
-      command:
-        type: string
-        required: true
-        description: Shell command to execute
-    execute:
-      type: builtin
-      parse_output: text
-
-prompt_snippet: |
-  You have access to a shell tool. Use it to run build, test, or inspection commands.
-  Avoid destructive commands. Prefer targeted commands over broad ones.

package/templates/tools/web-search.tool.yaml

@@ -1,24 +0,0 @@
-name: web-search
-description: Search the web using Tavily (requires TAVILY_API_KEY)
-version: 1
-
-commands:
-  - name: web_search-search
-    description: Search the web and return relevant results
-    parameters:
-      query:
-        type: string
-        required: true
-        description: The search query
-      max_results:
-        type: number
-        required: false
-        description: "Maximum number of results to return (default: 5)"
-    execute:
-      type: builtin
-      parse_output: json
-
-prompt_snippet: |
-  You have access to a web search tool. Use it to find up-to-date information from the web.
-  Search in the language most relevant to the query (English for technical docs, French for local content).
-  Prefer specific, targeted queries over broad ones for better results.

package/tests/anonymization-middleware.test.ts

@@ -1,61 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { AnonymizationMiddleware } from '../src/middleware/anonymization.js';
-
-describe('AnonymizationMiddleware', () => {
-  it('anonymizes text containing PII', () => {
-    const mw = new AnonymizationMiddleware();
-    const result = mw.anonymize('Contact mc@acme.com');
-    expect(result).not.toContain('mc@acme.com');
-    expect(result).toContain('EMAIL_1');
-  });
-
-  it('deanonymizes using accumulated keymap', () => {
-    const mw = new AnonymizationMiddleware();
-    const anon = mw.anonymize('Contact mc@acme.com');
-    const restored = mw.deanonymize(anon);
-    expect(restored).toBe('Contact mc@acme.com');
-  });
-
-  it('is consistent across multiple calls (same email = same token)', () => {
-    const mw = new AnonymizationMiddleware();
-    const first = mw.anonymize('Email mc@acme.com here');
-    const second = mw.anonymize('Also mc@acme.com again');
-    expect(first).toContain('EMAIL_1');
-    expect(second).toContain('EMAIL_1');
-    // Verify deanonymize restores both
-    expect(mw.deanonymize(first)).toBe('Email mc@acme.com here');
-    expect(mw.deanonymize(second)).toBe('Also mc@acme.com again');
-  });
-
-  it('accumulates keymap across calls', () => {
-    const mw = new AnonymizationMiddleware();
-    mw.anonymize('Email mc@acme.com');
-    mw.anonymize('Phone 514-555-1234');
-    const keymap = mw.getKeymap();
-    expect(keymap['EMAIL_1']).toBe('mc@acme.com');
-    expect(keymap['PHONE_1']).toBe('514-555-1234');
-  });
-
-  it('handles JSON round-trip', () => {
-    const mw = new AnonymizationMiddleware();
-    const obj = { email: 'mc@acme.com', message: 'hello' };
-    const anonStr = mw.anonymize(JSON.stringify(obj));
-    const restored = JSON.parse(mw.deanonymize(anonStr));
-    expect(restored.email).toBe('mc@acme.com');
-  });
-
-  it('passes through text with no PII unchanged', () => {
-    const mw = new AnonymizationMiddleware();
-    const text = 'Calculate 2 + 2 = 4';
-    expect(mw.anonymize(text)).toBe(text);
-    expect(mw.deanonymize(text)).toBe(text);
-  });
-
-  it('new email in second call gets EMAIL_2 (not EMAIL_1 again)', () => {
-    const mw = new AnonymizationMiddleware();
-    mw.anonymize('Email mc@acme.com');
-    const second = mw.anonymize('Other other@example.com');
-    expect(second).toContain('EMAIL_2');
-    expect(mw.getKeymap()['EMAIL_2']).toBe('other@example.com');
-  });
-});