@studio-foundation/api 0.3.0-beta.1

package/tests/validate.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildServer } from '../src/server.js';
+import { InMemoryRunStore } from '@studio-foundation/engine';
+import type { IntegrationRuntime } from '../src/integration-runtime.js';
+import type { IntegrationStore } from '../src/integration-store.js';
+
+const TMP = resolve('/tmp', `.studio-validate-test-${Date.now()}`);
+
+const nullIntegrationRuntime = { registerRoutes: () => {} } as unknown as IntegrationRuntime;
+const nullIntegrationStore = {} as unknown as IntegrationStore;
+
+function makeServer() {
+  return buildServer({
+    store: new InMemoryRunStore(),
+    launcher: { launch: async () => ({ run_id: 'x' }), cancel: async () => {} },
+    configsDir: TMP,
+    projectName: 'test-project',
+    apiConfig: {},
+    studioVersion: '0.0.0-test',
+    maskedConfig: { providers: [] },
+    integrationRuntime: nullIntegrationRuntime,
+    integrationStore: nullIntegrationStore,
+  });
+}
+
+beforeAll(() => {
+  mkdirSync(resolve(TMP, 'agents'), { recursive: true });
+  mkdirSync(resolve(TMP, 'contracts'), { recursive: true });
+  mkdirSync(resolve(TMP, 'tools'), { recursive: true });
+
+  writeFileSync(resolve(TMP, 'agents', 'analyst.agent.yaml'), 'name: analyst\nmodel: claude-sonnet-4-20250514\n');
+  writeFileSync(resolve(TMP, 'contracts', 'brief-analysis.contract.yaml'), 'name: brief-analysis\nversion: 1\n');
+  writeFileSync(resolve(TMP, 'tools', 'my-tool.tool.yaml'), 'name: my-tool\n');
+});
+
+afterAll(() => {
+  rmSync(TMP, { recursive: true, force: true });
+});
+
+describe('POST /api/validate', () => {
+  it('returns valid=true for a pipeline with existing agent and contract', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'pipeline',
+        name: 'feature-builder',
+        content: 'stages:\n  - name: analysis\n    agent: analyst\n    contract: brief-analysis\n',
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { valid: boolean; errors: string[] };
+    expect(body.valid).toBe(true);
+    expect(body.errors).toHaveLength(0);
+  });
+
+  it('returns errors for a pipeline referencing a missing agent', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'pipeline',
+        name: 'bad-pipeline',
+        content: 'stages:\n  - name: s1\n    agent: missing-agent\n    contract: brief-analysis\n',
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { valid: boolean; errors: string[] };
+    expect(body.valid).toBe(false);
+    expect(body.errors).toContain("Agent 'missing-agent' not found");
+  });
+
+  it('returns errors for a pipeline referencing a missing contract', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'pipeline',
+        name: 'bad-pipeline',
+        content: 'stages:\n  - name: s1\n    agent: analyst\n    contract: missing-contract\n',
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { valid: boolean; errors: string[] };
+    expect(body.valid).toBe(false);
+    expect(body.errors).toContain("Contract 'missing-contract' not found");
+  });
+
+  it('validates group stages recursively', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'pipeline',
+        name: 'grouped',
+        content: `stages:\n  - group: impl\n    max_iterations: 3\n    stages:\n      - name: code\n        agent: analyst\n        contract: missing-contract\n`,
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const { valid, errors } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(false);
+    expect(errors).toContain("Contract 'missing-contract' not found");
+  });
+
+  it('returns errors for agent with unknown tool', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'agent',
+        name: 'coder',
+        content: 'name: coder\ntools:\n  - repo_manager-write_file\n  - ghost-tool\n',
+      },
+    });
+    expect(res.statusCode).toBe(200);
+    const { valid, errors } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(false);
+    expect(errors).toContain("Tool 'ghost-tool' not found");
+  });
+
+  it('accepts agent with builtin tools', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'agent',
+        name: 'coder',
+        content: 'name: coder\ntools:\n  - repo_manager-write_file\n  - shell-run_command\n',
+      },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(true);
+  });
+
+  it('accepts agent with custom tools (exact plugin name)', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'agent',
+        name: 'coder',
+        content: 'name: coder\ntools:\n  - my-tool\n',
+      },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(true);
+  });
+
+  it('accepts agent with custom tool actions (plugin-action naming)', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'agent',
+        name: 'coder',
+        content: 'name: coder\ntools:\n  - my-tool-run\n',
+      },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(true);
+  });
+
+  it('returns parse error for invalid YAML', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: { type: 'contract', name: 'x', content: 'key: [unclosed' },
+    });
+    const { valid, errors } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(false);
+    expect(errors[0]).toMatch(/YAML parse error/);
+  });
+
+  it('validates skill as valid when non-empty', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: { type: 'skill', name: 'my-skill', content: '# My skill\nDo this thing.' },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(true);
+  });
+
+  it('validates empty skill as invalid', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: { type: 'skill', name: 'my-skill', content: '   ' },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(false);
+  });
+
+  it('returns error when pipeline has no stages array', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: { type: 'pipeline', name: 'p', content: 'name: my-pipeline\n' },
+    });
+    const { valid, errors } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(false);
+    expect(errors).toContain('Pipeline must have a "stages" array');
+  });
+
+  it('returns valid=true for a well-formed contract', async () => {
+    const server = makeServer();
+    const res = await server.inject({
+      method: 'POST',
+      url: '/api/validate',
+      payload: {
+        type: 'contract',
+        name: 'c',
+        content: 'name: my-contract\nversion: 1\nschema:\n  required_fields:\n    - summary\n',
+      },
+    });
+    const { valid } = res.json() as { valid: boolean; errors: string[] };
+    expect(valid).toBe(true);
+  });
+});

package/tests/webhook-dispatcher.test.ts

@@ -0,0 +1,214 @@
+import { describe, test, expect, vi, beforeEach, afterEach } from 'vitest';
+import { resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { WebhookStore } from '../src/webhook-store.js';
+import { WebhookDispatcher } from '../src/webhook-dispatcher.js';
+
+type FetchCall = { url: string; options: RequestInit };
+
+function makeStore(): { store: WebhookStore; cleanup: () => void } {
+  const dir = resolve('/tmp', `.studio-dispatcher-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(dir, { recursive: true });
+  const store = new WebhookStore(resolve(dir, 'runs.db'));
+  return { store, cleanup: () => store.close() };
+}
+
+function makeFetch(status = 200): { fetch: typeof fetch; calls: FetchCall[] } {
+  const calls: FetchCall[] = [];
+  const mockFetch = vi.fn(async (url: string | URL | Request, options?: RequestInit) => {
+    calls.push({ url: url.toString(), options: options ?? {} });
+    return new Response('OK', { status });
+  }) as unknown as typeof fetch;
+  return { fetch: mockFetch, calls };
+}
+
+describe('WebhookDispatcher', () => {
+  let store: WebhookStore;
+  let cleanup: () => void;
+
+  beforeEach(() => {
+    ({ store, cleanup } = makeStore());
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  test('dispatches pipeline_complete to matching webhook', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', {
+      pipeline_name: 'feature-builder',
+      run_id: 'run-1',
+      status: 'success',
+      duration_ms: 1000,
+      total_tokens: 100,
+      total_tool_calls: 2,
+    });
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0].url).toBe('https://hook.example.com/cb');
+  });
+
+  test('does not dispatch when event type does not match webhook subscription', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['stage_failed'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    expect(calls).toHaveLength(0);
+  });
+
+  test('includes X-Studio-Event header', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    const headers = calls[0].options.headers as Record<string, string>;
+    expect(headers['X-Studio-Event']).toBe('pipeline_complete');
+  });
+
+  test('includes X-Studio-Signature header when webhook has a secret', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], secret: 'mysecret', status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    const headers = calls[0].options.headers as Record<string, string>;
+    expect(headers['X-Studio-Signature']).toMatch(/^sha256=[a-f0-9]{64}$/);
+  });
+
+  test('does not include X-Studio-Signature when no secret configured', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    const headers = calls[0].options.headers as Record<string, string>;
+    expect(headers['X-Studio-Signature']).toBeUndefined();
+  });
+
+  test('payload contains run_id, event, ts fields', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-42', 'pipeline_complete', { status: 'success' });
+
+    const body = JSON.parse(calls[0].options.body as string);
+    expect(body.run_id).toBe('run-42');
+    expect(body.event).toBe('pipeline_complete');
+    expect(body.ts).toBeDefined();
+  });
+
+  test('maps stage_complete with rejected status to stage_rejected webhook event', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['stage_rejected'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'stage_complete', { stage_name: 'qa', status: 'rejected' });
+
+    expect(calls).toHaveLength(1);
+    const body = JSON.parse(calls[0].options.body as string);
+    expect(body.event).toBe('stage_rejected');
+  });
+
+  test('maps stage_complete with failed status to stage_failed webhook event', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['stage_failed'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'stage_complete', { stage_name: 'code', status: 'failed' });
+
+    expect(calls).toHaveLength(1);
+    const body = JSON.parse(calls[0].options.body as string);
+    expect(body.event).toBe('stage_failed');
+  });
+
+  test('maps stage_complete with success status to stage_complete webhook event', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['stage_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'stage_complete', { stage_name: 'code', status: 'success' });
+
+    expect(calls).toHaveLength(1);
+    const body = JSON.parse(calls[0].options.body as string);
+    expect(body.event).toBe('stage_complete');
+  });
+
+  test('does not dispatch to failed webhooks', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://hook.example.com/cb', events: ['pipeline_complete'], status: 'failed', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    expect(calls).toHaveLength(0);
+  });
+
+  test('dispatches to multiple matching webhooks', async () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.example.com/hook', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    store.saveWebhook({ id: 'wh-2', url: 'https://b.example.com/hook', events: ['pipeline_complete', 'stage_failed'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const { fetch, calls } = makeFetch();
+    const dispatcher = new WebhookDispatcher(store, 'my-project', fetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    expect(calls).toHaveLength(2);
+  });
+
+  test('retries on HTTP 5xx and marks webhook failed after 3 failed retries', async () => {
+    vi.useFakeTimers();
+    let callCount = 0;
+    const failingFetch = vi.fn(async () => {
+      callCount++;
+      return new Response('Error', { status: 500 });
+    }) as unknown as typeof fetch;
+
+    const { store: s, cleanup: c } = makeStore();
+    s.saveWebhook({ id: 'wh-fail', url: 'https://fail.example.com/hook', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const dispatcher = new WebhookDispatcher(s, 'test', failingFetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+
+    // Advance through all retry delays: 30s + 5min + 15min
+    await vi.advanceTimersByTimeAsync(30_001);
+    await vi.advanceTimersByTimeAsync(5 * 60_001);
+    await vi.advanceTimersByTimeAsync(15 * 60_001);
+
+    expect(callCount).toBe(4); // 1 original + 3 retries
+    expect(s.getWebhook('wh-fail')?.status).toBe('failed');
+
+    c();
+    vi.useRealTimers();
+  });
+
+  test('does not retry on successful delivery', async () => {
+    vi.useFakeTimers();
+    let callCount = 0;
+    const successFetch = vi.fn(async () => {
+      callCount++;
+      return new Response('OK', { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const { store: s, cleanup: c } = makeStore();
+    s.saveWebhook({ id: 'wh-ok', url: 'https://ok.example.com/hook', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const dispatcher = new WebhookDispatcher(s, 'test', successFetch);
+
+    await dispatcher.handleBusEvent('run-1', 'pipeline_complete', { status: 'success' });
+    await vi.runAllTimersAsync();
+
+    expect(callCount).toBe(1);
+
+    c();
+    vi.useRealTimers();
+  });
+});

package/tests/webhook-store.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { WebhookStore, type WebhookRegistration, type WebhookDelivery } from '../src/webhook-store.js';
+
+describe('WebhookStore', () => {
+  let store: WebhookStore;
+
+  beforeEach(() => {
+    const dbDir = resolve('/tmp', `.studio-webhook-store-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(dbDir, { recursive: true });
+    store = new WebhookStore(resolve(dbDir, 'runs.db'));
+  });
+
+  afterEach(() => {
+    store.close();
+  });
+
+  test('saves and retrieves a webhook', () => {
+    const webhook: WebhookRegistration = {
+      id: 'wh-1',
+      url: 'https://example.com/webhook',
+      events: ['pipeline_complete', 'stage_failed'],
+      secret: 'secret123',
+      status: 'active',
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+    store.saveWebhook(webhook);
+    expect(store.getWebhook('wh-1')).toEqual(webhook);
+  });
+
+  test('returns null for unknown webhook', () => {
+    expect(store.getWebhook('nonexistent')).toBeNull();
+  });
+
+  test('lists all webhooks', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: ['pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    store.saveWebhook({ id: 'wh-2', url: 'https://b.com', events: ['stage_failed'], status: 'active', created_at: '2026-01-02T00:00:00.000Z' });
+    const webhooks = store.listWebhooks();
+    expect(webhooks).toHaveLength(2);
+    expect(webhooks.map(w => w.id)).toContain('wh-1');
+    expect(webhooks.map(w => w.id)).toContain('wh-2');
+  });
+
+  test('returns empty list when no webhooks', () => {
+    expect(store.listWebhooks()).toHaveLength(0);
+  });
+
+  test('deletes a webhook and returns true', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: [], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    expect(store.deleteWebhook('wh-1')).toBe(true);
+    expect(store.getWebhook('wh-1')).toBeNull();
+  });
+
+  test('deleteWebhook returns false for unknown id', () => {
+    expect(store.deleteWebhook('does-not-exist')).toBe(false);
+  });
+
+  test('marks webhook as failed', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: [], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    store.markWebhookFailed('wh-1');
+    expect(store.getWebhook('wh-1')?.status).toBe('failed');
+  });
+
+  test('saves a delivery without error', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: [], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const delivery: WebhookDelivery = {
+      id: 'del-1',
+      webhook_id: 'wh-1',
+      event: 'pipeline_complete',
+      run_id: 'run-1',
+      status: 'pending',
+      attempt: 1,
+      created_at: '2026-01-01T00:00:00.000Z',
+    };
+    expect(() => store.saveDelivery(delivery)).not.toThrow();
+  });
+
+  test('updates a delivery status without error', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: [], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    store.saveDelivery({
+      id: 'del-1',
+      webhook_id: 'wh-1',
+      event: 'pipeline_complete',
+      run_id: 'run-1',
+      status: 'pending',
+      attempt: 1,
+      created_at: '2026-01-01T00:00:00.000Z',
+    });
+    expect(() => store.updateDelivery('del-1', 'success')).not.toThrow();
+  });
+
+  test('persists events array as JSON', () => {
+    store.saveWebhook({ id: 'wh-1', url: 'https://a.com', events: ['pipeline_start', 'pipeline_complete'], status: 'active', created_at: '2026-01-01T00:00:00.000Z' });
+    const result = store.getWebhook('wh-1');
+    expect(result?.events).toEqual(['pipeline_start', 'pipeline_complete']);
+  });
+});