@studio-foundation/api 0.3.0-beta.1

package/src/routes/tools.ts

@@ -0,0 +1,222 @@
+import { readdir, readFile, writeFile, unlink, mkdir, access } 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 {
+  BUILTIN_TOOL_NAMES,
+  listAvailableToolTemplates,
+  getBundledToolTemplate,
+} from '@studio-foundation/runner';
+
+function toolPath(configsDir: string, name: string): string {
+  return join(configsDir, 'tools', `${name}.tool.yaml`);
+}
+
+async function isCustomTool(configsDir: string, name: string): Promise<boolean> {
+  try {
+    await access(toolPath(configsDir, name));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function toolsRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const { configsDir } = options.deps;
+  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+  // GET /api/tools — list builtins + custom
+  fastify.get('/tools', {
+    schema: {
+      tags: ['tools'],
+      summary: 'List all available tools (builtins + custom)',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            tools: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  description: { type: 'string' },
+                  is_builtin: { type: 'boolean' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    const toolsList: { name: string; description: string; is_builtin: boolean }[] = [];
+
+    // Builtins from bundled templates (skip if overridden by a custom file)
+    const available = await listAvailableToolTemplates();
+    for (const t of available) {
+      const overridden = await isCustomTool(configsDir, t.name);
+      if (!overridden) {
+        toolsList.push({ name: t.name, description: t.description, is_builtin: true });
+      }
+    }
+
+    // Custom tools from .studio/tools/
+    const toolsDir = join(configsDir, 'tools');
+    let entries: string[] = [];
+    try {
+      entries = await readdir(toolsDir);
+    } catch {
+      // dir doesn't exist — no custom tools
+    }
+    for (const file of entries.filter(f => f.endsWith('.tool.yaml'))) {
+      const name = file.replace('.tool.yaml', '');
+      const content = await readFile(join(toolsDir, file), 'utf-8');
+      const def = yaml.load(content) as { description?: string };
+      const isBuiltin = BUILTIN_TOOL_NAMES.has(name);
+      toolsList.push({ name, description: def.description ?? '', is_builtin: isBuiltin });
+    }
+
+    return reply.send({ tools: toolsList });
+  });
+
+  // GET /api/tools/:name — read a tool definition
+  fastify.get<{ Params: { name: string } }>('/tools/:name', {
+    schema: {
+      tags: ['tools'],
+      summary: 'Get a tool definition by name',
+      params: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+      response: {
+        200: { type: 'object', additionalProperties: true },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const { name } = request.params;
+
+    // Custom tool takes priority
+    if (await isCustomTool(configsDir, name)) {
+      const content = await readFile(toolPath(configsDir, name), 'utf-8');
+      const parsed = yaml.load(content) as Record<string, unknown>;
+      return reply.send({ ...parsed, is_builtin: BUILTIN_TOOL_NAMES.has(name) });
+    }
+
+    // Fall back to bundled builtin template
+    const template = await getBundledToolTemplate(name);
+    if (template) {
+      const parsed = yaml.load(template) as Record<string, unknown>;
+      return reply.send({ ...parsed, is_builtin: true });
+    }
+
+    return reply.status(404).send({ error: `Tool '${name}' not found` });
+  });
+
+  // PUT /api/tools/:name — create or update a custom tool
+  fastify.put<{ Params: { name: string }; Body: unknown }>(
+    '/tools/:name',
+    {
+      schema: {
+        tags: ['tools'],
+        summary: 'Create or update a custom tool (YAML text or JSON body)',
+        params: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+        body: { oneOf: [{ type: 'object', additionalProperties: true }, { type: 'string' }] },
+        response: {
+          200: { type: 'object', properties: { name: { type: 'string' } } },
+          400: errorSchema,
+        },
+      },
+    },
+    async (request, reply) => {
+      const { name } = request.params;
+      const contentType = request.headers['content-type'] ?? '';
+
+      let yamlContent: string;
+      if (contentType.includes('application/json')) {
+        yamlContent = yaml.dump(request.body);
+      } else {
+        yamlContent = request.body as string;
+      }
+
+      try {
+        yaml.load(yamlContent);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Invalid YAML';
+        return reply.status(400).send({ error: message });
+      }
+
+      await mkdir(join(configsDir, 'tools'), { recursive: true });
+      await writeFile(toolPath(configsDir, name), yamlContent, 'utf-8');
+      return reply.send({ name });
+    }
+  );
+
+  // DELETE /api/tools/:name — delete a custom tool (403 for builtins not overridden)
+  fastify.delete<{ Params: { name: string } }>('/tools/:name', {
+    schema: {
+      tags: ['tools'],
+      summary: 'Delete a custom tool',
+      params: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+      response: {
+        200: { type: 'object', properties: { deleted: { type: 'string' } } },
+        403: errorSchema,
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const { name } = request.params;
+
+    // 403 if builtin with no custom override file
+    if (BUILTIN_TOOL_NAMES.has(name) && !(await isCustomTool(configsDir, name))) {
+      return reply.status(403).send({ error: `Cannot delete builtin tool '${name}'` });
+    }
+
+    try {
+      await unlink(toolPath(configsDir, name));
+    } catch {
+      return reply.status(404).send({ error: `Tool '${name}' not found` });
+    }
+    return reply.send({ deleted: name });
+  });
+
+  // POST /api/tools/install — install from the bundled registry
+  fastify.post<{ Body: { name: string } }>('/tools/install', {
+    schema: {
+      tags: ['tools'],
+      summary: 'Install a tool from the bundled registry',
+      body: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        200: { type: 'object', properties: { installed: { type: 'string' } } },
+        404: errorSchema,
+        409: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const { name } = request.body;
+
+    const template = await getBundledToolTemplate(name);
+    if (!template) {
+      const available = await listAvailableToolTemplates();
+      return reply.status(404).send({
+        error: `Tool '${name}' not found in registry. Available: ${available.map(t => t.name).join(', ')}`,
+      });
+    }
+
+    const destPath = toolPath(configsDir, name);
+    const alreadyInstalled = await access(destPath).then(() => true).catch(() => false);
+    if (alreadyInstalled) {
+      return reply.status(409).send({ error: `Tool '${name}' is already installed` });
+    }
+
+    await mkdir(join(configsDir, 'tools'), { recursive: true });
+    await writeFile(destPath, template, 'utf-8');
+    return reply.send({ installed: name });
+  });
+}

package/src/routes/users.ts

@@ -0,0 +1,169 @@
+// api/src/routes/users.ts
+import { randomUUID, randomBytes } from 'node:crypto';
+import type { FastifyInstance } from 'fastify';
+import type { ServerDeps } from '../server.js';
+
+const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+const userSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    email: { type: 'string' },
+    plan: { type: 'string' },
+    created_at: { type: 'string' },
+  },
+};
+
+const userWithKeySchema = {
+  ...userSchema,
+  properties: { ...userSchema.properties, api_key: { type: 'string' } },
+};
+
+const todayUsageSchema = {
+  type: 'object',
+  properties: {
+    runs_count: { type: 'number' },
+    tokens_used: { type: 'number' },
+  },
+};
+
+const userWithUsageSchema = {
+  type: 'object',
+  properties: {
+    ...userSchema.properties,
+    today_usage: todayUsageSchema,
+  },
+};
+
+export async function usersRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps },
+): Promise<void> {
+  const { userStore } = options.deps;
+  if (!userStore) return; // no-op if userStore not configured
+
+  // POST /api/users — create a user
+  fastify.post<{ Body: { email: string; plan?: string } }>('/users', {
+    schema: {
+      tags: ['users'],
+      summary: 'Create a new user',
+      body: {
+        type: 'object',
+        required: ['email'],
+        properties: {
+          email: { type: 'string', format: 'email' },
+          plan: { type: 'string', default: 'free' },
+        },
+      },
+      response: {
+        201: userWithKeySchema,
+        400: errorSchema,
+        409: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const { email, plan = 'free' } = request.body;
+
+    const apiKey = randomBytes(32).toString('hex');
+    const user = {
+      id: randomUUID(),
+      email,
+      plan,
+      api_key: apiKey,
+      created_at: new Date().toISOString(),
+    };
+
+    try {
+      await userStore.saveUser(user);
+    } catch (err: unknown) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.includes('UNIQUE constraint failed: users.email')) {
+        return reply.status(409).send({ error: 'Email already in use' });
+      }
+      throw err;
+    }
+    return reply.status(201).send(user);
+  });
+
+  // GET /api/users — list users (no api_key exposed)
+  fastify.get('/users', {
+    schema: {
+      tags: ['users'],
+      summary: 'List all users',
+      response: {
+        200: { type: 'array', items: userSchema },
+      },
+    },
+  }, async (_request, reply) => {
+    const users = await userStore.listUsers();
+    return reply.send(users.map(({ api_key: _k, ...u }) => u));
+  });
+
+  // GET /api/users/me — current user + today usage
+  fastify.get('/users/me', {
+    schema: {
+      tags: ['users'],
+      summary: 'Get current authenticated user',
+      response: {
+        200: userWithUsageSchema,
+        401: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    if (!request.user) return reply.status(401).send({ error: 'Unauthorized' });
+
+    const today = new Date().toISOString().slice(0, 10);
+    const usage = await userStore.getDailyUsage(request.user.id, today);
+    const { api_key: _k, ...userWithoutKey } = request.user;
+
+    return reply.send({
+      ...userWithoutKey,
+      today_usage: { runs_count: usage.runs_count, tokens_used: usage.tokens_used },
+    });
+  });
+
+  // GET /api/users/:id — user detail + today usage
+  fastify.get<{ Params: { id: string } }>('/users/:id', {
+    schema: {
+      tags: ['users'],
+      summary: 'Get a user by ID',
+      params: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      response: {
+        200: userWithUsageSchema,
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const user = await userStore.getUserById(request.params.id);
+    if (!user) return reply.status(404).send({ error: 'User not found' });
+
+    const today = new Date().toISOString().slice(0, 10);
+    const usage = await userStore.getDailyUsage(user.id, today);
+    const { api_key: _k, ...userWithoutKey } = user;
+
+    return reply.send({
+      ...userWithoutKey,
+      today_usage: { runs_count: usage.runs_count, tokens_used: usage.tokens_used },
+    });
+  });
+
+  // DELETE /api/users/:id
+  fastify.delete<{ Params: { id: string } }>('/users/:id', {
+    schema: {
+      tags: ['users'],
+      summary: 'Delete a user',
+      params: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      response: {
+        204: { type: 'null', description: 'No content' },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const user = await userStore.getUserById(request.params.id);
+    if (!user) return reply.status(404).send({ error: 'User not found' });
+
+    await userStore.deleteUser(request.params.id);
+    return reply.status(204).send();
+  });
+}

package/src/routes/validate.ts

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

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