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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@studio-foundation/api",
-  "version": "0.3.0-beta.1",
+  "version": "0.3.0-beta.5",
   "description": "HTTP API for Studio v7",
   "type": "module",
   "main": "./dist/api.js",
@@ -21,6 +21,9 @@
   "bin": {
     "studio-api": "./dist/index.js"
   },
+  "files": [
+    "dist"
+  ],
   "keywords": [
     "studio",
     "api"
@@ -36,9 +39,9 @@
     "fastify": "^5.3.2",
     "js-yaml": "^4.1.1",
     "pg": "^8.19.0",
-    "@studio-foundation/contracts": "0.3.0-beta.1",
-    "@studio-foundation/engine": "0.3.0-beta.1",
-    "@studio-foundation/runner": "0.3.0-beta.1"
+    "@studio-foundation/engine": "0.3.0-beta.5",
+    "@studio-foundation/runner": "0.3.0-beta.5",
+    "@studio-foundation/contracts": "0.3.0-beta.5"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.8",

package/ARCHITECTURE.md

@@ -1,52 +0,0 @@
-# @studio-foundation/api
-
-Serveur HTTP REST pour Studio. Même engine que le CLI, interface machine-to-machine.
-
-## Concept
-
-`bootstrap(cwd)` trouve `.studio/`, câble engine + store + launcher + integrations.
-`buildServer()` crée le serveur Fastify avec toutes les routes et le Swagger UI.
-Résultat : Linear webhook → pipeline run → SSE streaming → webhook dispatch.
-
-## Règles
-
-- Le API est aussi un **composition root** — même pattern que CLI, dépend de `@studio-foundation/engine` et `@studio-foundation/runner`
-- Toute route Fastify **DOIT** avoir un schema Swagger complet (tags, summary, params, response). Sans ça, la route n'apparaît pas dans Swagger UI.
-- Le engine est appelé via `InProcessLauncher` — pas de HTTP round-trip interne sauf pour `HttpApiSpawner`
-- Swagger UI désactivé en production (`NODE_ENV=production`)
-- Auth Bearer optionnelle : si `api.key` dans `config.yaml`, toutes les routes l'exigent
-- DB configurable : `db.type: sqlite | postgres | inmemory` dans `config.yaml`
-
-## Fichiers clés
-
-- `bootstrap.ts` — `bootstrap(cwd)` : trouve `.studio/`, crée store + engine + launcher + integrations
-- `server.ts` — `buildServer()` : Fastify factory, monte toutes les routes
-- `launcher.ts` — `InProcessLauncher` : lance les pipelines en arrière-plan, publie sur le bus d'événements
-- `event-bus.ts` — `RunEventBus` : bus interne SSE (run events → clients connectés)
-- `routes/runs.ts` — `GET/POST /api/runs`, SSE `/api/runs/:id/stream`, cancel
-- `routes/pipelines.ts`, `agents.ts`, `contracts.ts`, `skills.ts` — CRUD YAML
-- `routes/tools.ts` — `GET /api/tools`
-- `routes/projects.ts` — `GET /api/projects`
-- `routes/config.ts` — `GET/PUT /api/config`
-- `routes/validate.ts` — `POST /api/validate`
-- `routes/webhooks.ts` — enregistrement webhooks
-- `webhook-store.ts`, `webhook-dispatcher.ts` — persistence + dispatch webhooks
-- `integration-store.ts`, `integration-runtime.ts` — lifecycle intégrations
-- `integrations/linear/webhook-handler.ts` — handler Linear (drag → run → comment → move)
-- `spawners/http-api-spawner.ts` — `HttpApiSpawner` : spawner auto-référentiel pour `studio_run`
-
-## Séquence bootstrap
-
-```
-findStudioDir(cwd)
-  → loadConfig (config.yaml + ${ENV_VAR} substitution)
-  → createRunStore (SQLite | PostgreSQL | InMemory)
-  → createProviderRegistry + ToolRegistry
-  → loadProjectTools (.tool.yaml) + loadPlugins (MCP)
-  → new HttpApiSpawner → EngineConfig → InProcessLauncher
-  → WebhookStore + IntegrationStore + IntegrationRuntime
-```
-
-## Dépendances
-
-`@studio-foundation/engine`, `@studio-foundation/runner`, `@studio-foundation/contracts`

package/src/api.ts

@@ -1,8 +0,0 @@
-// Named exports for programmatic use (CLI, tests)
-export { bootstrap } from './bootstrap.js';
-export { buildServer } from './server.js';
-export type { ServerDeps, ApiConfig } from './server.js';
-export type { RunLauncher, LaunchConfig } from './launcher.js';
-export { InProcessLauncher, generateRunId } from './launcher.js';
-export { cloneRepo, resolveRepoPath } from './utils/repo-resolver.js';
-export type { RepoResolveOptions } from './utils/repo-resolver.js';

package/src/bootstrap.ts

@@ -1,259 +0,0 @@
-// Bootstrap — finds .studio/, loads config, creates engine + store + launcher
-// Same pattern as CLI but without terminal output
-
-import { resolve, join, dirname } from 'node:path';
-import { access, readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-import yaml from 'js-yaml';
-import {
-  type EngineConfig,
-  SQLiteRunStore,
-  InMemoryRunStore,
-  PgRunStore,
-  type AnyRunStore,
-} from '@studio-foundation/engine';
-import {
-  createDefaultRegistry,
-  ToolRegistry,
-  loadProjectTools,
-  loadPlugins,
-  loadProjectIntegrations,
-  MCPClient,
-  type SkillContent,
-} from '@studio-foundation/runner';
-import { InProcessLauncher, type RunLauncher } from './launcher.js';
-import { RunEventBus } from './event-bus.js';
-import type { MaskedConfig } from './server.js';
-import { WebhookStore } from './webhook-store.js';
-import { WebhookDispatcher } from './webhook-dispatcher.js';
-import { IntegrationStore } from './integration-store.js';
-import { IntegrationRuntime } from './integration-runtime.js';
-import { HttpApiSpawner } from './spawners/http-api-spawner.js';
-import { resolvePlans, type PlansConfig } from './plans.js';
-import { UserStore } from './user-store.js';
-import { PgUserStore } from './user-store-pg.js';
-
-export interface StudioApiConfig {
-  providers?: {
-    openai?: { apiKey: string };
-    anthropic?: { apiKey: string };
-    ollama?: { baseUrl?: string };   // ADD THIS
-  };
-  paths?: { projects_dir?: string };
-  defaults?: { provider?: string; model?: string };
-  api?: { key?: string; port?: number };
-  integrations?: Record<string, Record<string, unknown>>;
-  db?: {
-    type?: 'sqlite' | 'postgres' | 'inmemory';
-    url?: string;
-  };
-  plans?: Record<string, {
-    runs_per_day?: number;
-    max_concurrent?: number;
-    max_tokens_per_run?: number;
-    rate_limit_per_minute?: number;
-  }>;
-}
-
-export interface BootstrapResult {
-  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: { key?: string; port?: number };
-  cleanup: () => Promise<void>;
-  studioVersion: string;
-  maskedConfig: MaskedConfig;
-  webhookStore: WebhookStore;
-  integrationStore: IntegrationStore;
-  integrationRuntime: IntegrationRuntime;
-  userStore: UserStore | PgUserStore;
-  plans: PlansConfig;
-}
-
-async function findStudioDir(startDir: string): Promise<string | null> {
-  let current = resolve(startDir);
-  while (true) {
-    const candidate = join(current, '.studio');
-    try {
-      await access(candidate);
-      return candidate;
-    } catch {
-      // not here, go up
-    }
-    const parent = dirname(current);
-    if (parent === current) return null;
-    current = parent;
-  }
-}
-
-export async function bootstrap(cwd: string = process.cwd()): Promise<BootstrapResult> {
-  const studioDir = await findStudioDir(cwd);
-  if (!studioDir) {
-    throw new Error(`No .studio/ directory found from ${cwd}. Run 'studio init' first.`);
-  }
-
-  // Load config
-  let config: StudioApiConfig = {};
-  try {
-    const raw = await readFile(join(studioDir, 'config.yaml'), 'utf-8');
-    // Resolve env vars
-    const resolved = raw.replace(/\$\{([^}]+)\}/g, (_m: string, v: string) => process.env[v.trim()] ?? '');
-    config = (yaml.load(resolved) as StudioApiConfig) ?? {};
-  } catch {
-    // No config.yaml — use defaults
-  }
-
-  // Read studio version from api/package.json
-  const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
-  const pkgRaw = await readFile(pkgPath, 'utf-8');
-  const studioVersion = (JSON.parse(pkgRaw) as { version: string }).version;
-
-  // Build masked config — provider names only, no API keys
-  const maskedConfig = {
-    defaults: config.defaults,
-    providers: Object.keys(config.providers ?? {}),
-  };
-
-  const runsDir = join(studioDir, 'runs');
-
-  const dbType = config.db?.type ?? 'sqlite';
-
-  // WebhookStore and IntegrationStore are always SQLite — they are separate from RunStore
-  const dbPath = join(studioDir, 'runs', 'runs.db');
-
-  let store: AnyRunStore;
-  if (dbType === 'postgres') {
-    const url = config.db?.url;
-    if (!url) throw new Error('db.url is required when db.type is postgres');
-    store = new PgRunStore(url);
-  } else if (dbType === 'inmemory') {
-    store = new InMemoryRunStore();
-  } else {
-    store = new SQLiteRunStore(dbPath);
-  }
-
-  // UserStore — same DB as run store
-  let userStore: UserStore | PgUserStore;
-  if (dbType === 'postgres') {
-    const url = config.db?.url;
-    if (!url) throw new Error('db.url is required when db.type is postgres');
-    userStore = new PgUserStore(url);
-  } else {
-    userStore = new UserStore(dbPath);
-  }
-
-  const plans = resolvePlans(config.plans as Record<string, import('./plans.js').PlanLimits> | undefined);
-
-  const providerRegistry = createDefaultRegistry({
-    openai: config.providers?.openai ? { apiKey: config.providers.openai.apiKey } : undefined,
-    anthropic: config.providers?.anthropic ? { apiKey: config.providers.anthropic.apiKey } : undefined,
-    ollama: config.providers?.ollama ? { baseUrl: config.providers.ollama.baseUrl } : undefined,
-  });
-
-  const toolsDir = join(studioDir, 'tools');
-  const loadedPlugins = await loadProjectTools(toolsDir, cwd);
-  const toolRegistry = new ToolRegistry();
-  for (const plugin of loadedPlugins) {
-    toolRegistry.registerPlugin(plugin.name, plugin.tools, plugin.promptSnippet);
-  }
-
-  // Load MCP plugins
-  const pluginsDir = join(studioDir, 'plugins');
-  const pluginManifests = await loadPlugins(pluginsDir);
-  const mcpClients: InstanceType<typeof MCPClient>[] = [];
-  const pluginSkills: Record<string, string[]> = {};
-
-  for (const manifest of pluginManifests) {
-    for (const [serverName, serverDef] of Object.entries(manifest.mcpServers)) {
-      const client = new MCPClient(manifest.name, serverName, serverDef);
-      try {
-        await client.start();
-        const mcpTools = await client.getTools();
-        toolRegistry.registerPlugin(`${manifest.name}-${serverName}`, mcpTools);
-        mcpClients.push(client);
-      } catch {
-        // Plugin failed to start — skip silently for API
-      }
-    }
-    if (manifest.skills.length > 0) {
-      pluginSkills[manifest.name] = manifest.skills.map(
-        (s: SkillContent) => `## Skill: ${s.name}\n\n${s.content}`
-      );
-    }
-  }
-
-  // Self-referential spawner: allows pipelines to spawn child runs via the API
-  // Must match DEFAULT_PORT in index.ts (3700) — was 3000 which collides with common dev servers
-  const apiPort = config.api?.port ?? 3700;
-  const spawner = new HttpApiSpawner(`http://localhost:${apiPort}`, config.api?.key);
-
-  const engineConfig: EngineConfig = {
-    configsDir: studioDir,
-    providerRegistry,
-    toolRegistry,
-    db: store,
-    pluginSkills,
-    spawner,
-    maxDepth: 3,
-    defaultProvider: config.defaults?.provider,
-    defaultModel: config.defaults?.model,
-  };
-
-  const bus = new RunEventBus();
-  const launcher = new InProcessLauncher(engineConfig, store, runsDir, bus);
-
-  // Derive project name from the directory containing .studio/
-  const projectName = studioDir.split('/').slice(-2, -1)[0] ?? 'studio-project';
-
-  const webhookStore = new WebhookStore(dbPath);
-  const integrationStore = new IntegrationStore(dbPath);
-  const integrationsDir = join(studioDir, 'integrations');
-  const loadedIntegrations = await loadProjectIntegrations(integrationsDir);
-  const integrationConfigs = (config.integrations ?? {}) as Record<string, Record<string, unknown>>;
-  const integrationRuntime = new IntegrationRuntime({
-    integrations: loadedIntegrations,
-    store: integrationStore,
-    launcher,
-    configsDir: studioDir,
-    projectsDir: config.paths?.projects_dir,
-    apiConfig: config.api ?? {},
-    integrationConfigs,
-  });
-  integrationRuntime.setupEventBus(bus);
-  const webhookDispatcher = new WebhookDispatcher(webhookStore, projectName);
-  bus.subscribeAll((runId, event) => {
-    void webhookDispatcher.handleBusEvent(runId, event.type, event.data);
-  });
-
-  return {
-    store,
-    launcher,
-    configsDir: studioDir,
-    projectsDir: config.paths?.projects_dir,
-    projectName,
-    apiConfig: config.api ?? {},
-    studioVersion,
-    maskedConfig,
-    webhookStore,
-    integrationStore,
-    integrationRuntime,
-    userStore,
-    plans,
-    cleanup: async () => {
-      for (const client of mcpClients) {
-        try { await client.close(); } catch { /* ignore */ }
-      }
-      if ('close' in store && typeof (store as AnyRunStore & { close?: () => unknown }).close === 'function') {
-        await (store as AnyRunStore & { close(): Promise<void> | void }).close();
-      }
-      if (userStore && 'close' in userStore && typeof userStore.close === 'function') {
-        await userStore.close();
-      }
-      webhookStore.close();
-      integrationStore.close();
-    },
-  };
-}

package/src/event-bus.ts

@@ -1,64 +0,0 @@
-export type SseEventType =
-  | 'pipeline_start'
-  | 'stage_start'
-  | 'stage_complete'
-  | 'stage_retry'
-  | 'group_start'
-  | 'group_iteration'
-  | 'group_feedback'
-  | 'group_complete'
-  | 'pipeline_complete'
-  | 'pipeline_cancelled'
-  | 'stage_context'
-  | 'tool_call_start'
-  | 'tool_call_complete'
-  | 'done';
-
-export interface BusEvent {
-  type: SseEventType;
-  data: unknown;
-}
-
-export type BusListener = (event: BusEvent) => void;
-export type GlobalBusListener = (runId: string, event: BusEvent) => void;
-
-export class RunEventBus {
-  private subs = new Map<string, Set<BusListener>>();
-  private globalListeners = new Set<GlobalBusListener>();
-
-  subscribe(runId: string, listener: BusListener): () => void {
-    if (!this.subs.has(runId)) {
-      this.subs.set(runId, new Set());
-    }
-    this.subs.get(runId)!.add(listener);
-    return () => {
-      this.subs.get(runId)?.delete(listener);
-    };
-  }
-
-  // Global subscription — receives all events across all runs
-  subscribeAll(listener: GlobalBusListener): () => void {
-    this.globalListeners.add(listener);
-    return () => {
-      this.globalListeners.delete(listener);
-    };
-  }
-
-  emit(runId: string, type: SseEventType, data: unknown): void {
-    const event: BusEvent = { type, data };
-    const listeners = this.subs.get(runId);
-    if (listeners) {
-      for (const listener of listeners) {
-        listener(event);
-      }
-    }
-    for (const listener of this.globalListeners) {
-      listener(runId, event);
-    }
-  }
-
-  close(runId: string): void {
-    this.emit(runId, 'done', {});
-    this.subs.delete(runId);
-  }
-}

package/src/index.ts

@@ -1,58 +0,0 @@
-#!/usr/bin/env node
-// Standalone entrypoint for @studio/api
-// PM2: pm2 start node_modules/.bin/studio-api --env STUDIO_CWD=/path/to/project
-// systemd: ExecStart=/usr/bin/node /path/to/api/dist/index.js
-
-import { bootstrap } from './bootstrap.js';
-import { buildServer } from './server.js';
-
-const DEFAULT_PORT = 3700;
-
-async function main() {
-  const cwd = process.env['STUDIO_CWD'] ?? process.cwd();
-
-  let result: Awaited<ReturnType<typeof bootstrap>>;
-  try {
-    result = await bootstrap(cwd);
-  } catch (err) {
-    console.error('Bootstrap failed:', err instanceof Error ? err.message : String(err));
-    process.exit(1);
-  }
-
-  const { store, launcher, configsDir, projectName, apiConfig, cleanup, studioVersion, maskedConfig, webhookStore, integrationStore, integrationRuntime, userStore, plans } = result;
-  const port = apiConfig.port ?? DEFAULT_PORT;
-
-  let hasUsers = false;
-  try {
-    // listUsers() is sync on UserStore and async on PgUserStore; await handles both
-    const users = await userStore.listUsers();
-    hasUsers = users.length > 0;
-  } catch {
-    // DB unavailable at startup — default to open/dev mode
-  }
-
-  const server = buildServer({ store, launcher, configsDir, projectName, apiConfig, studioVersion, maskedConfig, webhookStore, integrationStore, integrationRuntime, userStore, plans, hasUsers });
-
-  // Graceful shutdown
-  const shutdown = async () => {
-    await server.close();
-    await cleanup();
-    process.exit(0);
-  };
-  process.on('SIGTERM', () => void shutdown());
-  process.on('SIGINT', () => void shutdown());
-
-  try {
-    await server.listen({ port, host: '0.0.0.0' });
-    console.log(`Studio API listening on port ${port}`);
-    if (!apiConfig.key) {
-      console.log('Warning: no api.key configured — running without auth');
-    }
-  } catch (err) {
-    console.error('Failed to start server:', err);
-    await cleanup();
-    process.exit(1);
-  }
-}
-
-void main();

package/src/integration-runtime.ts

@@ -1,180 +0,0 @@
-// api/src/integration-runtime.ts
-import type { FastifyInstance } from 'fastify';
-import type { IntegrationPluginDef } from '@studio-foundation/contracts';
-import type { IntegrationStore } from './integration-store.js';
-import type { RunLauncher } from './launcher.js';
-import type { RunEventBus } from './event-bus.js';
-import type { ApiConfig } from './server.js';
-import { WEBHOOK_HANDLERS, FAILURE_HANDLERS } from './integrations/registry.js';
-import type { FailureHandlerContext } from './integrations/types.js';
-import type { GroupFeedbackEvent } from '@studio-foundation/engine';
-
-export interface IntegrationRuntimeDeps {
-  integrations: IntegrationPluginDef[];
-  store: IntegrationStore;
-  launcher: RunLauncher;
-  configsDir: string;
-  projectsDir?: string;
-  apiConfig: ApiConfig;
-  integrationConfigs: Record<string, Record<string, unknown>>;
-}
-
-export class IntegrationRuntime {
-  constructor(private deps: IntegrationRuntimeDeps) {}
-
-  setupEventBus(bus: RunEventBus): void {
-    bus.subscribeAll((runId, event) => {
-      if (event.type !== 'pipeline_complete') return;
-
-      const data = event.data as {
-        status: string;
-        duration_ms: number;
-        meta?: Record<string, unknown>;
-        last_group_feedback?: GroupFeedbackEvent;
-      };
-
-      if (data.status === 'success') return;
-
-      for (const integration of this.deps.integrations) {
-        if (!integration.on_failure?.handler) continue;
-        const handler = FAILURE_HANDLERS[integration.on_failure.handler];
-        if (!handler) continue;
-
-        const ctx: FailureHandlerContext = {
-          runId,
-          durationMs: data.duration_ms,
-          status: data.status,
-          meta: data.meta ?? {},
-          lastGroupFeedback: data.last_group_feedback,
-          integration,
-          integrationConfig: this.deps.integrationConfigs[integration.name] ?? {},
-        };
-
-        void handler.handleFailure(ctx);
-      }
-    });
-  }
-
-  registerRoutes(fastify: FastifyInstance, prefix: string): void {
-    for (const integration of this.deps.integrations) {
-      if (!integration.webhook?.handler) continue;
-      const webhookHandler = WEBHOOK_HANDLERS[integration.webhook.handler];
-      if (!webhookHandler) continue;
-
-      const name = integration.name;
-      const { store, launcher, configsDir, projectsDir, apiConfig, integrationConfigs } = this.deps;
-      const integrationConfig = integrationConfigs[name] ?? {};
-      const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
-
-      void fastify.register(async (scope) => {
-        scope.addContentTypeParser(
-          'application/json',
-          { parseAs: 'buffer' },
-          (_req, body, done) => done(null, body),
-        );
-
-        // GET /api/integrations/{name}
-        scope.get(`${prefix}/integrations/${name}`, {
-          schema: {
-            tags: ['integrations'],
-            summary: `Get ${name} integration config and trigger log`,
-            response: {
-              200: {
-                type: 'object',
-                properties: {
-                  webhook_url: { type: 'string' },
-                  pipeline: { type: ['string', 'null'] },
-                  active: { type: 'boolean' },
-                  triggers: { type: 'array' },
-                },
-              },
-            },
-          },
-        }, async (request, reply) => {
-          const config = store.getConfig(name);
-          const triggers = store.listTriggers(name, 50);
-          const baseUrl = process.env['STUDIO_BASE_URL'] ?? `${request.protocol}://${request.hostname}`;
-          return reply.status(200).send({
-            webhook_url: `${baseUrl}/api/integrations/${name}/webhook`,
-            pipeline: config.pipeline ?? null,
-            active: config.active,
-            triggers,
-          });
-        });
-
-        // PATCH /api/integrations/{name}
-        scope.patch(`${prefix}/integrations/${name}`, {
-          schema: {
-            tags: ['integrations'],
-            summary: `Update ${name} integration config`,
-            body: {
-              type: 'object',
-              properties: {
-                pipeline: { type: 'string' },
-                active: { type: 'boolean' },
-              },
-            },
-            response: {
-              200: {
-                type: 'object',
-                properties: {
-                  webhook_url: { type: 'string' },
-                  pipeline: { type: ['string', 'null'] },
-                  active: { type: 'boolean' },
-                },
-              },
-              400: errorSchema,
-            },
-          },
-        }, async (request, reply) => {
-          let data: { pipeline?: string; active?: boolean };
-          try {
-            data = JSON.parse((request.body as Buffer).toString('utf-8')) as typeof data;
-          } catch {
-            return reply.status(400).send({ error: 'Invalid JSON' });
-          }
-          store.patchConfig(name, data);
-          const updated = store.getConfig(name);
-          const baseUrl = process.env['STUDIO_BASE_URL'] ?? `${request.protocol}://${request.hostname}`;
-          return reply.status(200).send({
-            webhook_url: `${baseUrl}/api/integrations/${name}/webhook`,
-            pipeline: updated.pipeline ?? null,
-            active: updated.active,
-          });
-        });
-
-        // POST /api/integrations/{name}/webhook
-        scope.post(`${prefix}/integrations/${name}/webhook`, {
-          schema: {
-            tags: ['integrations'],
-            summary: `Receive ${name} webhook event`,
-            response: {
-              202: {
-                type: 'object',
-                properties: { run_id: { type: 'string' }, stream_url: { type: 'string' } },
-              },
-              200: {
-                type: 'object',
-                properties: { ignored: { type: 'boolean' }, reason: { type: 'string' } },
-              },
-              400: errorSchema,
-              401: errorSchema,
-            },
-          },
-        }, async (request, reply) => {
-          return webhookHandler.handle({
-            rawBody: request.body as Buffer,
-            headers: request.headers,
-            integration,
-            store,
-            launcher,
-            configsDir,
-            projectsDir,
-            apiConfig,
-            integrationConfig,
-          }, reply);
-        });
-      });
-    }
-  }
-}