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

package/src/routes/validate.ts

@@ -1,196 +0,0 @@
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import yaml from 'js-yaml';
-import type { FastifyInstance } from 'fastify';
-import type { ServerDeps } from '../server.js';
-import {
-  createRepoManagerTools,
-  createShellTools,
-  createSearchTools,
-  createPatchTools,
-  createGitTools,
-} from '@studio-foundation/runner';
-
-// Derived at module load from the actual factory functions — single source of truth.
-// Using '.' as a dummy repoPath: only `execute` uses the path, `name` is hardcoded.
-const BUILTIN_TOOL_ACTIONS: Set<string> = new Set([
-  ...createRepoManagerTools('.').map(t => t.name),
-  ...createShellTools('.').map(t => t.name),
-  ...createSearchTools('.').map(t => t.name),
-  ...createPatchTools('.').map(t => t.name),
-  ...createGitTools('.').map(t => t.name),
-]);
-
-async function listNames(dir: string, suffix: string): Promise<Set<string>> {
-  try {
-    const entries = await readdir(dir);
-    return new Set(
-      entries
-        .filter(f => f.endsWith(suffix))
-        .map(f => f.slice(0, -suffix.length))
-    );
-  } catch {
-    return new Set();
-  }
-}
-
-/**
- * Read tool plugin YAMLs and return the `name` field from each.
- * Falls back to the filename stem if the YAML cannot be parsed.
- */
-async function listToolPluginNames(dir: string): Promise<Set<string>> {
-  try {
-    const { readFile } = await import('node:fs/promises');
-    const entries = await readdir(dir);
-    const names = new Set<string>();
-    await Promise.all(
-      entries
-        .filter(f => f.endsWith('.tool.yaml'))
-        .map(async (f) => {
-          try {
-            const raw = await readFile(join(dir, f), 'utf-8');
-            const parsed = yaml.load(raw) as Record<string, unknown> | null;
-            const name = parsed && typeof parsed.name === 'string'
-              ? parsed.name
-              : f.slice(0, -'.tool.yaml'.length);
-            names.add(name);
-          } catch {
-            names.add(f.slice(0, -'.tool.yaml'.length));
-          }
-        })
-    );
-    return names;
-  } catch {
-    return new Set();
-  }
-}
-
-type StageRef = { agents: string[]; contracts: string[] };
-
-function collectStageRefs(stage: Record<string, unknown>): StageRef {
-  const agents: string[] = [];
-  const contracts: string[] = [];
-  if (typeof stage.agent === 'string') agents.push(stage.agent);
-  if (typeof stage.contract === 'string') contracts.push(stage.contract);
-  // Recurse into group stages
-  if (Array.isArray(stage.stages)) {
-    for (const s of stage.stages) {
-      if (s && typeof s === 'object' && !Array.isArray(s)) {
-        const inner = collectStageRefs(s as Record<string, unknown>);
-        agents.push(...inner.agents);
-        contracts.push(...inner.contracts);
-      }
-    }
-  }
-  return { agents, contracts };
-}
-
-export async function validateRoutes(
-  fastify: FastifyInstance,
-  options: { deps: ServerDeps }
-): Promise<void> {
-  const { configsDir } = options.deps;
-
-  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
-
-  fastify.post<{
-    Body: { type: string; name?: string; content: string };
-  }>('/validate', {
-    schema: {
-      tags: ['validate'],
-      summary: 'Validate a Studio config for structural coherence',
-      body: {
-        type: 'object',
-        required: ['type', 'content'],
-        properties: {
-          type: {
-            type: 'string',
-            enum: ['pipeline', 'contract', 'agent', 'tool', 'skill'],
-          },
-          name: { type: 'string' },
-          content: { type: 'string' },
-        },
-      },
-      response: {
-        200: {
-          type: 'object',
-          properties: {
-            valid: { type: 'boolean' },
-            errors: { type: 'array', items: { type: 'string' } },
-          },
-          required: ['valid', 'errors'],
-        },
-        400: errorSchema,
-      },
-    },
-  }, async (request, reply) => {
-    const { type, content } = request.body;
-    const errors: string[] = [];
-
-    // Skills are markdown — just check non-empty
-    if (type === 'skill') {
-      if (!content.trim()) errors.push('Skill content is empty');
-      return reply.send({ valid: errors.length === 0, errors });
-    }
-
-    // Parse YAML
-    let parsed: unknown;
-    try {
-      parsed = yaml.load(content);
-    } catch (e) {
-      errors.push(`YAML parse error: ${e instanceof Error ? e.message : String(e)}`);
-      return reply.send({ valid: false, errors });
-    }
-
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      errors.push('Content must be a YAML object');
-      return reply.send({ valid: false, errors });
-    }
-
-    const obj = parsed as Record<string, unknown>;
-
-    if (type === 'pipeline') {
-      const stages = obj.stages;
-      if (!Array.isArray(stages)) {
-        errors.push('Pipeline must have a "stages" array');
-        return reply.send({ valid: false, errors });
-      }
-
-      const [agentNames, contractNames] = await Promise.all([
-        listNames(join(configsDir, 'agents'), '.agent.yaml'),
-        listNames(join(configsDir, 'contracts'), '.contract.yaml'),
-      ]);
-
-      for (const stage of stages) {
-        if (!stage || typeof stage !== 'object' || Array.isArray(stage)) continue;
-        const { agents: refs_a, contracts: refs_c } = collectStageRefs(
-          stage as Record<string, unknown>
-        );
-        for (const agent of refs_a) {
-          if (!agentNames.has(agent)) errors.push(`Agent '${agent}' not found`);
-        }
-        for (const contract of refs_c) {
-          if (!contractNames.has(contract)) errors.push(`Contract '${contract}' not found`);
-        }
-      }
-    }
-
-    if (type === 'agent') {
-      const toolsUsed = obj.tools;
-      if (Array.isArray(toolsUsed)) {
-        const customPlugins = await listToolPluginNames(join(configsDir, 'tools'));
-        for (const tool of toolsUsed) {
-          if (typeof tool !== 'string') continue;
-          // Custom tool actions follow <plugin>-<action> naming (e.g. claude_code-run
-          // from claude_code.tool.yaml). Match if any plugin name is a prefix.
-          const isCustom = [...customPlugins].some(p => tool === p || tool.startsWith(p + '-'));
-          if (!BUILTIN_TOOL_ACTIONS.has(tool) && !isCustom) {
-            errors.push(`Tool '${tool}' not found`);
-          }
-        }
-      }
-    }
-
-    return reply.send({ valid: errors.length === 0, errors });
-  });
-}

package/src/routes/webhooks.ts

@@ -1,120 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import type { FastifyInstance } from 'fastify';
-import type { ServerDeps } from '../server.js';
-
-const VALID_EVENTS = [
-  'pipeline_start',
-  'pipeline_complete',
-  'stage_complete',
-  'stage_rejected',
-  'stage_failed',
-  'group_feedback',
-] as const;
-
-const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
-
-const webhookSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    url: { type: 'string' },
-    events: { type: 'array', items: { type: 'string' } },
-    status: { type: 'string', enum: ['active', 'failed'] },
-    created_at: { type: 'string' },
-  },
-};
-
-export async function webhooksRoutes(
-  fastify: FastifyInstance,
-  options: { deps: ServerDeps },
-): Promise<void> {
-  const { webhookStore } = options.deps;
-
-  // POST /api/webhooks
-  fastify.post<{
-    Body: { url: string; events: string[]; secret?: string };
-  }>('/webhooks', {
-    schema: {
-      tags: ['webhooks'],
-      summary: 'Register a new webhook',
-      body: {
-        type: 'object',
-        required: ['url', 'events'],
-        properties: {
-          url: { type: 'string' },
-          events: { type: 'array', items: { type: 'string' }, minItems: 1 },
-          secret: { type: 'string' },
-        },
-      },
-      response: {
-        201: webhookSchema,
-        400: errorSchema,
-      },
-    },
-  }, async (request, reply) => {
-    const { url, events, secret } = request.body;
-
-    if (!events || events.length === 0) {
-      return reply.status(400).send({ error: 'events must not be empty' });
-    }
-
-    const id = randomUUID();
-    const created_at = new Date().toISOString();
-
-    webhookStore.saveWebhook({
-      id,
-      url,
-      events,
-      ...(secret != null ? { secret } : {}),
-      status: 'active',
-      created_at,
-    });
-
-    return reply.status(201).send({ id, url, events, status: 'active', created_at });
-  });
-
-  // GET /api/webhooks
-  fastify.get('/webhooks', {
-    schema: {
-      tags: ['webhooks'],
-      summary: 'List all registered webhooks',
-      response: {
-        200: {
-          type: 'object',
-          properties: {
-            webhooks: { type: 'array', items: webhookSchema },
-          },
-        },
-      },
-    },
-  }, async (_request, reply) => {
-    const webhooks = webhookStore.listWebhooks().map(({ secret: _secret, ...w }) => w);
-    return reply.send({ webhooks });
-  });
-
-  // DELETE /api/webhooks/:id
-  fastify.delete<{ Params: { id: string } }>('/webhooks/:id', {
-    schema: {
-      tags: ['webhooks'],
-      summary: 'Delete a webhook',
-      params: {
-        type: 'object',
-        properties: { id: { type: 'string' } },
-        required: ['id'],
-      },
-      response: {
-        204: { type: 'null', description: 'No content' },
-        404: errorSchema,
-      },
-    },
-  }, async (request, reply) => {
-    const deleted = webhookStore.deleteWebhook(request.params.id);
-    if (!deleted) {
-      return reply.status(404).send({ error: 'Webhook not found' });
-    }
-    return reply.status(204).send();
-  });
-}
-
-// Export VALID_EVENTS for documentation/validation use
-export { VALID_EVENTS };

package/src/server.ts

@@ -1,155 +0,0 @@
-// Fastify server builder — takes deps via injection for testability
-// buildServer(deps) → FastifyInstance, ready to listen
-
-import Fastify, { type FastifyRequest } from 'fastify';
-import cors from '@fastify/cors';
-import rateLimit from '@fastify/rate-limit';
-import swagger from '@fastify/swagger';
-import swaggerUi from '@fastify/swagger-ui';
-import type { AnyRunStore } from '@studio-foundation/engine';
-import type { RunLauncher } from './launcher.js';
-import type { WebhookStore } from './webhook-store.js';
-import type { IntegrationStore } from './integration-store.js';
-import type { IntegrationRuntime } from './integration-runtime.js';
-import type { UserStore } from './user-store.js';
-import type { PgUserStore } from './user-store-pg.js';
-import { getPlanLimits, DEFAULT_PLANS, type PlansConfig } from './plans.js';
-import { runsRoutes } from './routes/runs.js';
-import { projectsRoutes } from './routes/projects.js';
-import { contractsRoutes } from './routes/contracts.js';
-import { pipelinesRoutes } from './routes/pipelines.js';
-import { toolsRoutes } from './routes/tools.js';
-import { agentsRoutes } from './routes/agents.js';
-import { configRoutes } from './routes/config.js';
-import { skillsRoutes } from './routes/skills.js';
-import { validateRoutes } from './routes/validate.js';
-import { webhooksRoutes } from './routes/webhooks.js';
-import { usersRoutes } from './routes/users.js';
-
-export interface ApiConfig {
-  key?: string;
-  port?: number;
-}
-
-export type MaskedConfig = {
-  defaults?: { provider?: string; model?: string };
-  providers: string[];
-};
-
-export interface ServerDeps {
-  store: AnyRunStore;
-  launcher: RunLauncher;
-  configsDir: string;
-  /** Raw projects_dir from config (may contain ~). Used by route handlers for repo cloning. */
-  projectsDir?: string;
-  projectName: string;
-  apiConfig: ApiConfig;
-  studioVersion: string;
-  maskedConfig: MaskedConfig;
-  webhookStore: WebhookStore;
-  integrationStore: IntegrationStore;
-  integrationRuntime: IntegrationRuntime;
-  userStore?: UserStore | PgUserStore;
-  plans?: PlansConfig;
-  /** true when at least one user exists in the DB — computed at bootstrap time to avoid per-request DB calls */
-  hasUsers?: boolean;
-}
-
-// request.user type augmentation for Fastify
-declare module 'fastify' {
-  interface FastifyRequest {
-    user?: import('./user-store.js').User;
-  }
-}
-
-export function buildServer(deps: ServerDeps) {
-  const fastify = Fastify({ logger: false });
-
-  // Register text/plain parser so PUT routes that accept YAML bodies work correctly.
-  // Without this, Fastify v5 cannot parse text/plain and body validation fails with 400.
-  fastify.addContentTypeParser('text/plain', { parseAs: 'string' }, (_req, body, done) => {
-    done(null, body);
-  });
-
-  void fastify.register(cors, { origin: true });
-
-  void fastify.register(rateLimit, {
-    global: true,
-    max: (req: FastifyRequest) => {
-      const planName = req.user?.plan ?? 'free';
-      const plans = deps.plans ?? DEFAULT_PLANS;
-      return getPlanLimits(plans, planName).rate_limit_per_minute;
-    },
-    timeWindow: '1 minute',
-    keyGenerator: (req: FastifyRequest) => req.user?.id ?? req.ip ?? 'anonymous',
-    addHeaders: {
-      'x-ratelimit-limit': true,
-      'x-ratelimit-remaining': true,
-      'x-ratelimit-reset': true,
-    },
-    allowList: (req: FastifyRequest) => req.url.startsWith('/api/integrations/'),
-  });
-
-  if (process.env['NODE_ENV'] !== 'production') {
-    void fastify.register(swagger, {
-      openapi: {
-        info: {
-          title: 'Studio API',
-          description: 'REST API for Studio pipeline orchestration',
-          version: '1.0.0',
-        },
-      },
-    });
-    void fastify.register(swaggerUi, {
-      routePrefix: '/api/docs',
-    });
-  }
-
-  // Auth hook — supports three modes:
-  //   1. Multi-user: userStore provided + hasUsers=true → lookup by api_key
-  //   2. Legacy single-key: hasUsers=false + api.key configured → Bearer check
-  //   3. Open/dev: no users, no api.key → allow all (local dev only)
-  fastify.addHook('onRequest', async (request, reply) => {
-    const path = request.url.split('?')[0];
-    if (path.startsWith('/api/integrations/')) return;
-
-    const auth = request.headers['authorization'];
-    const token = auth?.startsWith('Bearer ') ? auth.slice(7) : undefined;
-
-    if (deps.userStore && deps.hasUsers) {
-      // Multi-user mode: look up user by api_key
-      const user = token ? await deps.userStore.getUserByApiKey(token) : null;
-      if (!user) {
-        await reply.status(401).send({ error: 'Unauthorized' });
-        return;
-      }
-      request.user = user;
-      return;
-    }
-
-    // Legacy single-key mode
-    if (deps.apiConfig.key) {
-      if (!auth || auth !== `Bearer ${deps.apiConfig.key}`) {
-        await reply.status(401).send({ error: 'Unauthorized' });
-      }
-      return;
-    }
-
-    // No userStore with users, no api.key → open (local dev)
-  });
-
-  void fastify.register(runsRoutes, { prefix: '/api', deps });
-  void fastify.register(projectsRoutes, { prefix: '/api', deps });
-  void fastify.register(contractsRoutes, { prefix: '/api', deps });
-  void fastify.register(pipelinesRoutes, { prefix: '/api', deps });
-  void fastify.register(toolsRoutes, { prefix: '/api', deps });
-  void fastify.register(agentsRoutes, { prefix: '/api', deps });
-  void fastify.register(configRoutes, { prefix: '/api', deps });
-  void fastify.register(skillsRoutes, { prefix: '/api', deps });
-  void fastify.register(validateRoutes, { prefix: '/api', deps });
-  void fastify.register(webhooksRoutes, { prefix: '/api', deps });
-  void fastify.register(usersRoutes, { prefix: '/api', deps });
-  deps.integrationRuntime.registerRoutes(fastify, '/api');
-
-  return fastify;
-}

package/src/spawners/http-api-spawner.ts

@@ -1,96 +0,0 @@
-import type { RunSpawner, SpawnConfig, SpawnResult, PipelineRun } from '@studio-foundation/contracts';
-
-export class HttpApiSpawner implements RunSpawner {
-  constructor(private apiUrl: string, private apiKey?: string) {}
-
-  private authHeaders(): Record<string, string> {
-    return this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {};
-  }
-
-  async spawnAndWait(config: SpawnConfig): Promise<SpawnResult> {
-    // 1. Launch the run
-    const postRes = await fetch(`${this.apiUrl}/api/runs`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Studio-Depth': String(config.depth),
-        'X-Studio-Parent-Run-Id': config.parentRunId,
-        ...this.authHeaders(),
-      },
-      body: JSON.stringify({ pipeline: config.pipeline, input: config.input }),
-    });
-
-    if (!postRes.ok) {
-      const text = await postRes.text();
-      throw new Error(`Failed to launch child run: ${postRes.status} ${text}`);
-    }
-
-    const { run_id } = (await postRes.json()) as { run_id: string };
-
-    // 2. Wait for pipeline_complete via SSE
-    await this.waitForCompletion(run_id);
-
-    // 3. Fetch full run result to get output
-    const getRes = await fetch(`${this.apiUrl}/api/runs/${run_id}`, {
-      headers: { ...this.authHeaders() },
-    });
-    if (!getRes.ok) {
-      throw new Error(`Failed to fetch child run result ${run_id}: ${getRes.status}`);
-    }
-    const run = (await getRes.json()) as PipelineRun;
-
-    if (run.status === 'failed' || run.status === 'rejected' || run.status === 'cancelled') {
-      throw new Error(`Child run ${run_id} ${run.status}`);
-    }
-
-    const lastStage = [...run.stages].reverse().find(s => s.status === 'success');
-    const output = (lastStage as { output?: unknown } | undefined)?.output ?? null;
-
-    return { run_id, status: run.status, output };
-  }
-
-  private waitForCompletion(runId: string): Promise<void> {
-    return new Promise((resolve, reject) => {
-      fetch(`${this.apiUrl}/api/runs/${runId}/stream`, {
-        headers: { Accept: 'text/event-stream', ...this.authHeaders() },
-      })
-        .then(response => {
-          if (!response.ok || !response.body) {
-            reject(new Error(`SSE connection failed for run ${runId}: ${response.status}`));
-            return;
-          }
-          const reader = response.body.getReader();
-          const decoder = new TextDecoder();
-          let buffer = '';
-          let currentEventType = '';
-
-          const pump = (): Promise<void> =>
-            reader.read().then(({ done, value }) => {
-              if (done) {
-                reject(new Error(`SSE stream ended without pipeline_complete for run ${runId}`));
-                return;
-              }
-              buffer += decoder.decode(value, { stream: true });
-              const lines = buffer.split('\n');
-              buffer = lines.pop() ?? '';
-
-              for (const line of lines) {
-                if (line.startsWith('event: ')) {
-                  currentEventType = line.slice(7).trim();
-                } else if (line.startsWith('data: ') && currentEventType === 'pipeline_complete') {
-                  reader.cancel();
-                  resolve();
-                  return;
-                } else if (line === '') {
-                  currentEventType = '';
-                }
-              }
-              return pump();
-            });
-
-          pump().catch(reject);
-        })
-        .catch(reject);
-    });
-  }
-}