@studio-foundation/api 0.3.0-beta.1

package/src/server.ts

@@ -0,0 +1,155 @@
+// 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

@@ -0,0 +1,96 @@
+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);
+    });
+  }
+}

package/src/user-store-pg.ts

@@ -0,0 +1,138 @@
+// api/src/user-store-pg.ts
+// PgUserStore — PostgreSQL async variant of UserStore
+// Follows same pattern as PgRunStore in @studio/engine
+// Table prefix studio_ to avoid conflicts with user app tables
+
+import { createRequire } from 'node:module';
+import type { User, DailyUsage } from './user-store.js';
+export type { User, DailyUsage } from './user-store.js';
+
+export class PgUserStore {
+  private pool: import('pg').Pool;
+  private schemaReady: Promise<void> | null = null;
+
+  constructor(connectionString: string) {
+    const _require = createRequire(import.meta.url);
+    const { Pool } = _require('pg') as typeof import('pg');
+    this.pool = new Pool({ connectionString });
+  }
+
+  private ensureSchema(): Promise<void> {
+    if (!this.schemaReady) {
+      this.schemaReady = this.initSchema();
+    }
+    return this.schemaReady;
+  }
+
+  private async initSchema(): Promise<void> {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS studio_users (
+        id         TEXT PRIMARY KEY,
+        email      TEXT UNIQUE NOT NULL,
+        plan       TEXT NOT NULL DEFAULT 'free',
+        api_key    TEXT UNIQUE NOT NULL,
+        created_at TEXT NOT NULL
+      )
+    `);
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS studio_usage (
+        user_id     TEXT NOT NULL,
+        date        TEXT NOT NULL,
+        runs_count  INTEGER NOT NULL DEFAULT 0,
+        tokens_used INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (user_id, date)
+      )
+    `);
+  }
+
+  async getUserByApiKey(apiKey: string): Promise<User | null> {
+    await this.ensureSchema();
+    const res = await this.pool.query<User>(
+      'SELECT id, email, plan, api_key, created_at FROM studio_users WHERE api_key = $1',
+      [apiKey]
+    );
+    return res.rows[0] ?? null;
+  }
+
+  async getUserById(id: string): Promise<User | null> {
+    await this.ensureSchema();
+    const res = await this.pool.query<User>(
+      'SELECT id, email, plan, api_key, created_at FROM studio_users WHERE id = $1',
+      [id]
+    );
+    return res.rows[0] ?? null;
+  }
+
+  async getUserByEmail(email: string): Promise<User | null> {
+    await this.ensureSchema();
+    const res = await this.pool.query<User>(
+      'SELECT id, email, plan, api_key, created_at FROM studio_users WHERE email = $1',
+      [email]
+    );
+    return res.rows[0] ?? null;
+  }
+
+  async listUsers(): Promise<User[]> {
+    await this.ensureSchema();
+    const res = await this.pool.query<User>(
+      'SELECT id, email, plan, api_key, created_at FROM studio_users ORDER BY created_at ASC'
+    );
+    return res.rows;
+  }
+
+  async saveUser(user: User): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.query(
+      `INSERT INTO studio_users (id, email, plan, api_key, created_at)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (id) DO UPDATE SET
+         email      = EXCLUDED.email,
+         plan       = EXCLUDED.plan,
+         api_key    = EXCLUDED.api_key,
+         created_at = EXCLUDED.created_at`,
+      [user.id, user.email, user.plan, user.api_key, user.created_at]
+    );
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.query('DELETE FROM studio_users WHERE id = $1', [id]);
+  }
+
+  async getDailyUsage(userId: string, date: string): Promise<DailyUsage> {
+    await this.ensureSchema();
+    const res = await this.pool.query<DailyUsage>(
+      'SELECT user_id, date, runs_count, tokens_used FROM studio_usage WHERE user_id = $1 AND date = $2',
+      [userId, date]
+    );
+    return res.rows[0] ?? { user_id: userId, date, runs_count: 0, tokens_used: 0 };
+  }
+
+  async incrementRuns(userId: string, date: string): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.query(
+      `INSERT INTO studio_usage (user_id, date, runs_count, tokens_used)
+       VALUES ($1, $2, 1, 0)
+       ON CONFLICT (user_id, date) DO UPDATE SET
+         runs_count = studio_usage.runs_count + 1`,
+      [userId, date]
+    );
+  }
+
+  async incrementTokens(userId: string, date: string, tokens: number): Promise<void> {
+    await this.ensureSchema();
+    await this.pool.query(
+      `INSERT INTO studio_usage (user_id, date, runs_count, tokens_used)
+       VALUES ($1, $2, 0, $3)
+       ON CONFLICT (user_id, date) DO UPDATE SET
+         tokens_used = studio_usage.tokens_used + EXCLUDED.tokens_used`,
+      [userId, date, tokens]
+    );
+  }
+
+  async close(): Promise<void> {
+    await this.pool.end();
+  }
+}
+
+export type AnyUserStore = import('./user-store.js').UserStore | PgUserStore;

package/src/user-store.ts

@@ -0,0 +1,125 @@
+// api/src/user-store.ts
+// UserStore — SQLite persistence for users and daily usage
+// Follows same pattern as WebhookStore and IntegrationStore
+// Uses the same DB file as the run store (.studio/runs/runs.db)
+
+import { createRequire } from 'node:module';
+
+export interface User {
+  id: string;
+  email: string;
+  plan: string;
+  api_key: string;
+  created_at: string;
+}
+
+export interface DailyUsage {
+  user_id: string;
+  date: string;      // YYYY-MM-DD
+  runs_count: number;
+  tokens_used: number;
+}
+
+export class UserStore {
+  private db: import('better-sqlite3').Database;
+
+  constructor(dbPath: string) {
+    const _require = createRequire(import.meta.url);
+    const Database = _require('better-sqlite3') as new (path: string) => import('better-sqlite3').Database;
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.initSchema();
+  }
+
+  private initSchema(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS users (
+        id         TEXT PRIMARY KEY,
+        email      TEXT UNIQUE NOT NULL,
+        plan       TEXT NOT NULL DEFAULT 'free',
+        api_key    TEXT UNIQUE NOT NULL,
+        created_at TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS usage (
+        user_id    TEXT NOT NULL,
+        date       TEXT NOT NULL,
+        runs_count INTEGER NOT NULL DEFAULT 0,
+        tokens_used INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY (user_id, date)
+      );
+    `);
+  }
+
+  getUserByApiKey(apiKey: string): User | null {
+    const row = this.db
+      .prepare('SELECT id, email, plan, api_key, created_at FROM users WHERE api_key = ?')
+      .get(apiKey) as User | undefined;
+    return row ?? null;
+  }
+
+  getUserById(id: string): User | null {
+    const row = this.db
+      .prepare('SELECT id, email, plan, api_key, created_at FROM users WHERE id = ?')
+      .get(id) as User | undefined;
+    return row ?? null;
+  }
+
+  getUserByEmail(email: string): User | null {
+    const row = this.db
+      .prepare('SELECT id, email, plan, api_key, created_at FROM users WHERE email = ?')
+      .get(email) as User | undefined;
+    return row ?? null;
+  }
+
+  listUsers(): User[] {
+    return this.db
+      .prepare('SELECT id, email, plan, api_key, created_at FROM users ORDER BY created_at ASC')
+      .all() as User[];
+  }
+
+  saveUser(user: User): void {
+    this.db.prepare(`
+      INSERT INTO users (id, email, plan, api_key, created_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        email      = excluded.email,
+        plan       = excluded.plan,
+        api_key    = excluded.api_key,
+        created_at = excluded.created_at
+    `).run(user.id, user.email, user.plan, user.api_key, user.created_at);
+  }
+
+  deleteUser(id: string): void {
+    this.db.prepare('DELETE FROM users WHERE id = ?').run(id);
+  }
+
+  getDailyUsage(userId: string, date: string): DailyUsage {
+    const row = this.db
+      .prepare('SELECT user_id, date, runs_count, tokens_used FROM usage WHERE user_id = ? AND date = ?')
+      .get(userId, date) as DailyUsage | undefined;
+    return row ?? { user_id: userId, date, runs_count: 0, tokens_used: 0 };
+  }
+
+  incrementRuns(userId: string, date: string): void {
+    this.db.prepare(`
+      INSERT INTO usage (user_id, date, runs_count, tokens_used)
+      VALUES (?, ?, 1, 0)
+      ON CONFLICT (user_id, date) DO UPDATE SET
+        runs_count = runs_count + 1
+    `).run(userId, date);
+  }
+
+  incrementTokens(userId: string, date: string, tokens: number): void {
+    this.db.prepare(`
+      INSERT INTO usage (user_id, date, runs_count, tokens_used)
+      VALUES (?, ?, 0, ?)
+      ON CONFLICT (user_id, date) DO UPDATE SET
+        tokens_used = tokens_used + excluded.tokens_used
+    `).run(userId, date, tokens);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+}

package/src/utils/repo-resolver.ts

@@ -0,0 +1,3 @@
+// Re-exported from @studio/engine — implementation lives there
+export { resolveRepoPath, cloneRepo } from '@studio-foundation/engine';
+export type { RepoResolveOptions } from '@studio-foundation/engine';

package/src/webhook-dispatcher.ts

@@ -0,0 +1,142 @@
+// WebhookDispatcher — listens to pipeline events and delivers them to registered webhooks
+// Handles HMAC-SHA256 signing, retry logic (30s / 5min / 15min), and failure tracking
+
+import { createHmac, randomUUID } from 'node:crypto';
+import type { SseEventType } from './event-bus.js';
+import type { WebhookStore } from './webhook-store.js';
+
+export type WebhookEventType =
+  | 'pipeline_start'
+  | 'pipeline_complete'
+  | 'stage_complete'
+  | 'stage_rejected'
+  | 'stage_failed'
+  | 'group_feedback';
+
+// Retry delays in ms: attempt 1 failed → 30s, attempt 2 failed → 5min, attempt 3 failed → 15min
+const RETRY_DELAYS = [30_000, 5 * 60_000, 15 * 60_000];
+
+function mapToWebhookEvent(sseType: SseEventType, data: unknown): WebhookEventType | null {
+  switch (sseType) {
+    case 'pipeline_start':
+      return 'pipeline_start';
+    case 'pipeline_complete':
+      return 'pipeline_complete';
+    case 'stage_complete': {
+      const status = (data as { status?: string }).status;
+      if (status === 'rejected') return 'stage_rejected';
+      if (status === 'failed') return 'stage_failed';
+      return 'stage_complete';
+    }
+    case 'group_feedback':
+      return 'group_feedback';
+    default:
+      return null;
+  }
+}
+
+function sign(body: string, secret: string): string {
+  const hmac = createHmac('sha256', secret);
+  hmac.update(body, 'utf-8');
+  return `sha256=${hmac.digest('hex')}`;
+}
+
+export class WebhookDispatcher {
+  constructor(
+    private readonly store: WebhookStore,
+    private readonly projectName: string,
+    private readonly fetcher: typeof fetch = fetch,
+  ) {}
+
+  async handleBusEvent(runId: string, sseType: SseEventType, data: unknown): Promise<void> {
+    const webhookEvent = mapToWebhookEvent(sseType, data);
+    if (!webhookEvent) return;
+
+    const webhooks = this.store.listWebhooks().filter(
+      w => w.status === 'active' && w.events.includes(webhookEvent),
+    );
+
+    await Promise.all(
+      webhooks.map(webhook => this.dispatch(webhook.id, webhookEvent, runId, data, 1)),
+    );
+  }
+
+  private async dispatch(
+    webhookId: string,
+    event: WebhookEventType,
+    runId: string,
+    sourceData: unknown,
+    attempt: number,
+  ): Promise<void> {
+    const webhook = this.store.getWebhook(webhookId);
+    if (!webhook || webhook.status === 'failed') return;
+
+    const payload = {
+      event,
+      run_id: runId,
+      project: this.projectName,
+      ts: new Date().toISOString(),
+      ...(sourceData as object),
+    };
+
+    const body = JSON.stringify(payload);
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      'X-Studio-Event': event,
+    };
+    if (webhook.secret) {
+      headers['X-Studio-Signature'] = sign(body, webhook.secret);
+    }
+
+    const deliveryId = randomUUID();
+    this.store.saveDelivery({
+      id: deliveryId,
+      webhook_id: webhookId,
+      event,
+      run_id: runId,
+      status: 'pending',
+      attempt,
+      created_at: new Date().toISOString(),
+    });
+
+    try {
+      const response = await this.fetcher(webhook.url, {
+        method: 'POST',
+        headers,
+        body,
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (response.ok) {
+        this.store.updateDelivery(deliveryId, 'success');
+      } else {
+        this.handleFailure(webhookId, event, runId, sourceData, attempt, deliveryId);
+      }
+    } catch {
+      this.handleFailure(webhookId, event, runId, sourceData, attempt, deliveryId);
+    }
+  }
+
+  private handleFailure(
+    webhookId: string,
+    event: WebhookEventType,
+    runId: string,
+    sourceData: unknown,
+    attempt: number,
+    deliveryId: string,
+  ): void {
+    const maxAttempts = RETRY_DELAYS.length + 1; // 4 total (1 original + 3 retries)
+
+    if (attempt >= maxAttempts) {
+      this.store.updateDelivery(deliveryId, 'failed');
+      this.store.markWebhookFailed(webhookId);
+      return;
+    }
+
+    this.store.updateDelivery(deliveryId, 'retrying');
+    const delay = RETRY_DELAYS[attempt - 1];
+    setTimeout(() => {
+      void this.dispatch(webhookId, event, runId, sourceData, attempt + 1);
+    }, delay);
+  }
+}