@studio-foundation/api 0.3.0-beta.1

package/src/routes/contracts.ts

@@ -0,0 +1,205 @@
+import { readdir, readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import type { FastifyInstance } from 'fastify';
+import type { ServerDeps } from '../server.js';
+import { loadContract, validateOutput } from '@studio-foundation/engine';
+import type { ToolCall } from '@studio-foundation/contracts';
+
+export async function contractsRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const contractsDir = join(options.deps.configsDir, 'contracts');
+  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+  // GET /api/contracts
+  fastify.get('/contracts', {
+    schema: {
+      tags: ['contracts'],
+      summary: 'List all contract names',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            contracts: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    let entries: string[];
+    try {
+      entries = await readdir(contractsDir);
+    } catch {
+      return reply.send({ contracts: [] });
+    }
+    const contracts = entries
+      .filter(f => f.endsWith('.contract.yaml'))
+      .map(f => f.slice(0, -'.contract.yaml'.length));
+    return reply.send({ contracts });
+  });
+
+  // GET /api/contracts/:name
+  fastify.get<{ Params: { name: string } }>('/contracts/:name', {
+    schema: {
+      tags: ['contracts'],
+      summary: 'Get a contract by name',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        200: { type: 'object', additionalProperties: true },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const filePath = join(contractsDir, `${request.params.name}.contract.yaml`);
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      return reply.status(404).send({ error: 'Contract not found' });
+    }
+    return reply.send(yaml.load(content));
+  });
+
+  // PUT /api/contracts/:name
+  fastify.put<{
+    Params: { name: string };
+    Body: Record<string, unknown>;
+  }>('/contracts/:name', {
+    schema: {
+      tags: ['contracts'],
+      summary: 'Create or update a contract',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      body: { type: 'object' },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            content: { type: 'object', additionalProperties: true },
+          },
+        },
+        400: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const body = request.body;
+
+    if (!body['name'] || typeof body['name'] !== 'string') {
+      return reply.status(400).send({ error: "Contract must have a 'name' field (string)" });
+    }
+    if (body['version'] === undefined) {
+      return reply.status(400).send({ error: "Contract must have a 'version' field" });
+    }
+
+    await mkdir(contractsDir, { recursive: true });
+    const filePath = join(contractsDir, `${request.params.name}.contract.yaml`);
+    await writeFile(filePath, yaml.dump(body), 'utf-8');
+
+    return reply.send({ name: request.params.name, content: body });
+  });
+
+  // DELETE /api/contracts/:name
+  fastify.delete<{ Params: { name: string } }>('/contracts/:name', {
+    schema: {
+      tags: ['contracts'],
+      summary: 'Delete a contract',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        204: { type: 'null', description: 'No content' },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const filePath = join(contractsDir, `${request.params.name}.contract.yaml`);
+    try {
+      await unlink(filePath);
+    } catch {
+      return reply.status(404).send({ error: 'Contract not found' });
+    }
+    return reply.status(204).send();
+  });
+
+  // POST /api/contracts/:name/validate
+  fastify.post<{
+    Params: { name: string };
+    Body: { output: unknown; tool_calls?: ToolCall[] };
+  }>('/contracts/:name/validate', {
+    schema: {
+      tags: ['contracts'],
+      summary: 'Validate an output against a contract without running a pipeline',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      body: {
+        type: 'object',
+        required: ['output'],
+        properties: {
+          output: { type: 'object', additionalProperties: true },
+          tool_calls: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                id: { type: 'string' },
+                name: { type: 'string' },
+                arguments: { type: 'object', additionalProperties: true },
+                result: {},
+                error: { type: 'string' },
+              },
+              required: ['id', 'name'],
+            },
+          },
+        },
+      },
+      response: {
+        200: {
+          type: 'object',
+          required: ['valid', 'errors', 'warnings', 'post_validation'],
+          properties: {
+            valid: { type: 'boolean' },
+            errors: { type: 'array', items: { type: 'string' } },
+            warnings: { type: 'array', items: { type: 'string' } },
+            post_validation: {
+              type: 'object',
+              required: ['accepted'],
+              properties: {
+                accepted: { type: 'boolean' },
+                rejection_reason: { type: 'string' },
+                rejection_details: { type: 'array', items: { type: 'string' } },
+              },
+            },
+          },
+        },
+        400: errorSchema,
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    let contract;
+    try {
+      contract = await loadContract(request.params.name, contractsDir);
+    } catch {
+      return reply.status(404).send({ error: 'Contract not found' });
+    }
+
+    const { output, tool_calls = [] } = request.body;
+    const result = validateOutput(contract, output, tool_calls);
+    return reply.send(result);
+  });
+}

package/src/routes/pipelines.ts

@@ -0,0 +1,146 @@
+import { readdir, readFile, writeFile, unlink } 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';
+
+function pipelinePath(configsDir: string, name: string): string {
+  return join(configsDir, 'pipelines', `${name}.pipeline.yaml`);
+}
+
+export async function pipelinesRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const { configsDir } = options.deps;
+
+  // GET /api/pipelines — list all pipeline names
+  fastify.get('/pipelines', {
+    schema: {
+      tags: ['pipelines'],
+      summary: 'List all pipeline names',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            pipelines: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    const pipelinesDir = join(configsDir, 'pipelines');
+    let entries: string[];
+    try {
+      entries = await readdir(pipelinesDir);
+    } catch {
+      return reply.send({ pipelines: [] });
+    }
+    const pipelines = entries
+      .filter(f => f.endsWith('.pipeline.yaml'))
+      .map(f => f.replace('.pipeline.yaml', ''));
+    return reply.send({ pipelines });
+  });
+
+  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+  // GET /api/pipelines/:name — read a pipeline (YAML parsed to JSON)
+  fastify.get<{ Params: { name: string } }>('/pipelines/:name', {
+    schema: {
+      tags: ['pipelines'],
+      summary: 'Get a pipeline 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;
+    let content: string;
+    try {
+      content = await readFile(pipelinePath(configsDir, name), 'utf-8');
+    } catch {
+      return reply.status(404).send({ error: `Pipeline '${name}' not found` });
+    }
+    const parsed = yaml.load(content);
+    return reply.send(parsed);
+  });
+
+  // PUT /api/pipelines/:name — create or update a pipeline (YAML or JSON body)
+  fastify.put<{ Params: { name: string }; Body: unknown }>(
+    '/pipelines/:name',
+    {
+      schema: {
+        tags: ['pipelines'],
+        summary: 'Create or update a pipeline (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 writeFile(pipelinePath(configsDir, name), yamlContent, 'utf-8');
+      return reply.send({ name });
+    }
+  );
+
+  // DELETE /api/pipelines/:name — delete a pipeline
+  fastify.delete<{ Params: { name: string } }>('/pipelines/:name', {
+    schema: {
+      tags: ['pipelines'],
+      summary: 'Delete a pipeline',
+      params: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+      response: {
+        200: {
+          type: 'object',
+          properties: { deleted: { type: 'string' } },
+        },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    const { name } = request.params;
+    try {
+      await unlink(pipelinePath(configsDir, name));
+    } catch {
+      return reply.status(404).send({ error: `Pipeline '${name}' not found` });
+    }
+    return reply.send({ deleted: name });
+  });
+}

package/src/routes/projects.ts

@@ -0,0 +1,237 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import * as yaml from 'js-yaml';
+import { createHash } from 'node:crypto';
+import type { FastifyInstance } from 'fastify';
+import type { ServerDeps } from '../server.js';
+
+function projectId(configsDir: string): string {
+  return createHash('sha256').update(configsDir).digest('hex').slice(0, 12);
+}
+
+async function listResources(dir: string, suffix: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir);
+    return entries
+      .filter(f => f.endsWith(suffix))
+      .map(f => f.slice(0, -suffix.length));
+  } catch {
+    return [];
+  }
+}
+
+export async function projectsRoutes(
+  fastify: FastifyInstance,
+  options: { deps: ServerDeps }
+): Promise<void> {
+  const { configsDir, projectName, studioVersion, maskedConfig } = options.deps;
+  const id = projectId(configsDir);
+
+  const errorSchema = { type: 'object', properties: { error: { type: 'string' } } };
+
+  // GET /api/projects — returns the single project this API serves
+  fastify.get('/projects', {
+    schema: {
+      tags: ['projects'],
+      summary: 'List projects served by this API instance',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            projects: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  id: { type: 'string' },
+                  name: { type: 'string' },
+                  pipelines_dir: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    return reply.send({
+      projects: [
+        {
+          id,
+          name: projectName,
+          pipelines_dir: join(configsDir, 'pipelines'),
+        },
+      ],
+    });
+  });
+
+  // GET /api/projects/:id/pipelines
+  fastify.get<{ Params: { id: string } }>('/projects/:id/pipelines', {
+    schema: {
+      tags: ['projects'],
+      summary: 'List pipelines for a project',
+      params: {
+        type: 'object',
+        properties: { id: { type: 'string' } },
+        required: ['id'],
+      },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            pipelines: { type: 'array', items: { type: 'string' } },
+          },
+        },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    if (request.params.id !== id) {
+      return reply.status(404).send({ error: 'Project not found' });
+    }
+
+    const pipelinesDir = join(configsDir, 'pipelines');
+    let entries: string[];
+    try {
+      entries = await readdir(pipelinesDir);
+    } catch {
+      return reply.send({ pipelines: [] });
+    }
+
+    const pipelines = entries
+      .filter(f => f.endsWith('.pipeline.yaml'))
+      .map(f => f.replace('.pipeline.yaml', ''));
+
+    return reply.send({ pipelines });
+  });
+  // GET /api/projects/:id/inputs
+  fastify.get<{ Params: { id: string } }>('/projects/:id/inputs', {
+    schema: {
+      tags: ['projects'],
+      summary: 'List inputs for a project',
+      params: {
+        type: 'object',
+        properties: { id: { type: 'string' } },
+        required: ['id'],
+      },
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            inputs: { type: 'array', items: { type: 'string' } },
+          },
+        },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    if (request.params.id !== id) {
+      return reply.status(404).send({ error: 'Project not found' });
+    }
+
+    const inputsDir = join(configsDir, 'inputs');
+    let entries: string[];
+    try {
+      entries = await readdir(inputsDir);
+    } catch {
+      return reply.send({ inputs: [] });
+    }
+
+    const inputs = entries
+      .filter(f => f.endsWith('.input.yaml'))
+      .map(f => f.replace('.input.yaml', ''));
+
+    return reply.send({ inputs });
+  });
+
+
+  // GET /api/projects/:id/inputs/:name — read an input file (YAML parsed to JSON)
+  fastify.get<{ Params: { id: string; name: string } }>('/projects/:id/inputs/:name', {
+    schema: {
+      tags: ['projects'],
+      summary: 'Get an input file by name',
+      params: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+        },
+        required: ['id', 'name'],
+      },
+      response: {
+        200: { type: 'object', additionalProperties: true },
+        404: errorSchema,
+      },
+    },
+  }, async (request, reply) => {
+    if (request.params.id !== id) {
+      return reply.status(404).send({ error: 'Project not found' });
+    }
+
+    const filePath = join(configsDir, 'inputs', `${request.params.name}.input.yaml`);
+    let content: string;
+    try {
+      content = await readFile(filePath, 'utf-8');
+    } catch {
+      return reply.status(404).send({ error: 'Input not found' });
+    }
+    return reply.send(yaml.load(content));
+  });
+
+  // GET /api/project — full introspection of the current Studio project
+  fastify.get('/project', {
+    schema: {
+      tags: ['projects'],
+      summary: 'Introspect the current Studio project',
+      response: {
+        200: {
+          type: 'object',
+          properties: {
+            studio_version: { type: 'string' },
+            studio_dir: { type: 'string' },
+            config: {
+              type: 'object',
+              properties: {
+                defaults: {
+                  type: 'object',
+                  properties: {
+                    provider: { type: 'string' },
+                    model: { type: 'string' },
+                  },
+                },
+                providers: { type: 'array', items: { type: 'string' } },
+              },
+            },
+            pipelines: { type: 'array', items: { type: 'string' } },
+            contracts: { type: 'array', items: { type: 'string' } },
+            agents: { type: 'array', items: { type: 'string' } },
+            tools: { type: 'array', items: { type: 'string' } },
+            skills: { type: 'array', items: { type: 'string' } },
+            inputs: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      },
+    },
+  }, async (_request, reply) => {
+    const [pipelines, contracts, agents, tools, skills, inputs] = await Promise.all([
+      listResources(join(configsDir, 'pipelines'), '.pipeline.yaml'),
+      listResources(join(configsDir, 'contracts'), '.contract.yaml'),
+      listResources(join(configsDir, 'agents'), '.agent.yaml'),
+      listResources(join(configsDir, 'tools'), '.tool.yaml'),
+      listResources(join(configsDir, 'skills'), '.skill.md'),
+      listResources(join(configsDir, 'inputs'), '.input.yaml'),
+    ]);
+
+    return reply.send({
+      studio_version: studioVersion,
+      studio_dir: configsDir,
+      config: maskedConfig,
+      pipelines,
+      contracts,
+      agents,
+      tools,
+      skills,
+      inputs,
+    });
+  });
+}