clyops-api 0.0.0-stage → 0.3.0

package/dist/server.js

@@ -0,0 +1,518 @@
+// An HTTP API over a directory of clyops tools: one POST endpoint per tool,
+// validated and documented from its --help-json-schema.
+import { allowed, InputError, isTextType, loadTools, runTool, startTool, tail, toJsonSchema, watchTools, } from 'clyops-tools';
+import { JobQueue } from 'clyops-jobs';
+import { mcpHttpHandler } from 'clyops-mcp';
+import busboy from 'busboy';
+import express from 'express';
+import { createReadStream, createWriteStream, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { finished, pipeline } from 'node:stream/promises';
+import { plus, z } from 'plus-express';
+import { toZod } from './zod.js';
+const RunResponseSchema = z.object({
+    ok: z.boolean(),
+    exitCode: z.number().int().nullable(),
+    signal: z.string().nullable(),
+    timedOut: z.boolean(),
+    stdout: z.string().openapi({ description: 'Base64 when `stdoutEncoding` is `base64` (binary output)' }),
+    stdoutEncoding: z.literal('base64').optional(),
+    stdoutUrl: z.string().optional().openapi({ description: 'Where an async job\'s binary output is served' }),
+    stderr: z.string(),
+    truncated: z.boolean().optional(),
+    durationMs: z.number(),
+    command: z.array(z.string()),
+    json: z.unknown().optional(),
+});
+const JobSchema = z.object({
+    job_id: z.string(),
+    function: z.string(),
+    status: z.enum(['pending', 'processing', 'done', 'error']),
+    stage: z.string().nullable(),
+    started_at: z.string(),
+    updated_at: z.string(),
+    completed_at: z.string().nullable(),
+    error: z.string().nullable(),
+    result: RunResponseSchema.optional(),
+}).passthrough();
+const ErrorSchema = z.object({ error: z.string(), issues: z.unknown().optional() });
+const json = (schema, description) => ({ description, content: { 'application/json': { schema } } });
+/** A tool's declared binary stdout type, if any (spec section 1.3). */
+function binaryStdout(tool) {
+    const type = tool.schema.stdout?.contentType;
+    return type && !isTextType(type) ? type.split(';')[0].trim() : undefined;
+}
+/**
+ * Whether to answer with the raw stdout stream rather than the JSON envelope:
+ * declared binary output streams unless the client asks for JSON, and other
+ * output streams when it asks for application/octet-stream.
+ */
+function streams(tool, req) {
+    const accept = req.get('accept') ?? '';
+    return binaryStdout(tool) ? !accept.includes('application/json') : accept.includes('application/octet-stream');
+}
+/** The envelope as JSON: binary stdout base64-encoded. */
+function envelope(result) {
+    const { stdoutBuffer, ...rest } = result;
+    return stdoutBuffer ? { ...rest, stdout: stdoutBuffer.toString('base64'), stdoutEncoding: 'base64' } : rest;
+}
+/** A header-safe one-line summary of stderr, for the trailer. */
+function stderrTrailer(stderr) {
+    return tail(stderr, 3).join(' | ').replace(/[^\x20-\x7e]/g, '?').slice(-500);
+}
+/** Query values (strings, arrays of strings) typed by the input's JSON Schema, for a non-JSON body. */
+function queryInput(query, schema) {
+    const typed = (value, type) => {
+        if ((type === 'integer' || type === 'number') && /^-?[0-9]*\.?[0-9]+$/.test(value))
+            return Number(value);
+        if (type === 'boolean' && /^(true|1|yes|on)$/i.test(value))
+            return true;
+        if (type === 'boolean' && /^(false|0|no|off)$/i.test(value))
+            return false;
+        return value;
+    };
+    const out = {};
+    for (const [key, raw] of Object.entries(query)) {
+        if (key === 'async')
+            continue;
+        const values = (Array.isArray(raw) ? raw : [raw]).map(String);
+        const prop = schema.properties?.[key];
+        out[key] = prop?.type === 'array' ? values.map((v) => typed(v, prop.items?.type)) : typed(values[values.length - 1], prop?.type);
+    }
+    return out;
+}
+/** Fails a stream with a 413 once more than `limit` bytes have passed. */
+function limited(limit) {
+    let size = 0;
+    return new Transform({
+        transform(chunk, _enc, done) {
+            size += chunk.length;
+            if (size > limit)
+                return done(Object.assign(new Error(`request body is larger than ${limit} bytes`), { status: 413 }));
+            done(null, chunk);
+        },
+    });
+}
+/**
+ * A multipart body: the `args` part is the JSON input, the `stdin` part is
+ * saved as the tool's stdin, and a part named after a path-valued input is
+ * saved and its path given as that input (repeated for array inputs). Files
+ * go to `dir`; at most `limit` bytes in all.
+ */
+function readMultipart(req, tool, dir, limit) {
+    const schema = toJsonSchema(tool.schema);
+    return new Promise((resolve, reject) => {
+        const input = {};
+        let stdin;
+        let size = 0;
+        let n = 0;
+        const writes = [];
+        const bb = busboy({ headers: req.headers });
+        // Stop reading at the first problem; the rest of the body is discarded.
+        const fail = (err) => {
+            req.unpipe(bb);
+            req.resume();
+            reject(err);
+        };
+        const count = (bytes) => {
+            size += bytes;
+            if (size > limit)
+                fail(Object.assign(new Error(`request body is larger than ${limit} bytes`), { status: 413 }));
+            return size <= limit;
+        };
+        const save = (from, file) => {
+            const write = pipeline(from, createWriteStream(file));
+            write.catch(() => { }); // reported through fail or the close handler
+            writes.push(write);
+        };
+        bb.on('field', (name, value) => {
+            if (!count(Buffer.byteLength(value)))
+                return;
+            if (name === 'args') {
+                try {
+                    Object.assign(input, JSON.parse(value));
+                }
+                catch {
+                    fail(new InputError('the args part is not JSON'));
+                }
+            }
+            else if (name === 'stdin') {
+                stdin = join(dir, 'stdin');
+                save(Readable.from([value]), stdin);
+            }
+            else
+                input[name] = value;
+        });
+        bb.on('file', (name, stream, info) => {
+            const file = name === 'stdin' ? join(dir, 'stdin') : join(dir, `${n++}-${basename(info.filename || name)}`);
+            if (name === 'stdin')
+                stdin = file;
+            else if (schema.properties[name]?.type === 'array')
+                input[name] = [...(input[name] ?? []), file];
+            else
+                input[name] = file;
+            stream.on('data', (chunk) => void count(chunk.length));
+            save(stream, file);
+        });
+        bb.on('error', (err) => fail(err));
+        bb.on('close', () => Promise.all(writes).then(() => resolve({ input, stdin }), reject));
+        req.pipe(bb);
+    });
+}
+/**
+ * Build the Express app. With `watch`, the tool endpoints, the OpenAPI
+ * document and /mcp follow the tools directory as it changes; otherwise they
+ * are fixed when the app is built.
+ */
+export async function createApi(opts) {
+    const maxBody = opts.maxBody ?? 10 << 20;
+    // A job's files (spooled stdin, uploads, binary stdout) live until it is dropped.
+    const jobDirs = new Map();
+    const queue = new JobQueue({
+        concurrency: opts.concurrency,
+        onDrop: (record) => {
+            const dir = jobDirs.get(record.job_id);
+            if (dir)
+                rmSync(dir, { recursive: true, force: true });
+            jobDirs.delete(record.job_id);
+        },
+    });
+    const onError = (cmd, err) => process.emitWarning(cmd ? `skipping ${cmd.words.join(' ')}: ${err.message}` : err.message);
+    const withPaths = (tools) => tools.map((t) => ({ ...t, path: `/tools/${t.words.join('/')}` }));
+    // Everything documented in OpenAPI lives on a router rebuilt for each set of tools.
+    let api;
+    const swap = (loaded) => (api = buildRoutes(opts, ctx, loaded.tree, withPaths(loaded.tools)));
+    const ctx = { queue, jobDirs, maxBody };
+    const watcher = opts.watch
+        ? await watchTools(opts.root, { name: opts.name, filter: opts.filter, onError, onChange: (loaded) => opts.onReload?.(swap(loaded)) })
+        : undefined;
+    swap(watcher ? watcher.current() : await loadTools(opts.root, { name: opts.name, filter: opts.filter, onError }));
+    const app = express();
+    app.use(express.json({ limit: maxBody }));
+    const keys = Object.entries(opts.keys ?? {});
+    if (opts.apiKey || keys.length) {
+        app.use((req, res, next) => {
+            const given = req.get('x-api-key') ?? req.get('authorization')?.replace(/^Bearer\s+/i, '');
+            if (given && given === opts.apiKey)
+                res.locals.caller = { name: keys.length ? 'default' : undefined };
+            else {
+                const found = keys.find(([, k]) => given && k.key === given);
+                if (!found)
+                    return void res.status(401).json({ error: 'missing or wrong API key' });
+                res.locals.caller = { name: found[0], filter: { allow: found[1].allow, deny: found[1].deny } };
+            }
+            next();
+        });
+    }
+    app.get('/openapi.json', (_req, res) => {
+        res.json(documentStreams(api.registry.generateOpenAPIDocument(opts.apiKey || keys.length ? { security: [{ apiKey: [] }] } : {}), api.tools));
+    });
+    // A key only sees and runs the tools it may.
+    app.use((req, res, next) => {
+        const caller = res.locals.caller;
+        const tool = api.tools.find((t) => t.path === req.path);
+        if (tool && caller?.filter && !allowed(tool, caller.filter))
+            return void res.status(403).json({ error: `this key may not run ${tool.words.join(' ')}` });
+        next();
+    });
+    // A non-JSON body is the tool's stdin (the arguments come from the query
+    // string), or multipart with the arguments, stdin and files.
+    app.use((req, res, next) => {
+        const tool = req.method === 'POST' && req.headers['content-type'] && !req.is('application/json') && api.tools.find((t) => t.path === req.path);
+        if (!tool)
+            return next();
+        void runBody(opts, ctx, tool, req, res).catch(next);
+    });
+    // RouterPlus's type drops Router's call signature; it is still a Router.
+    app.use((req, res, next) => api.router(req, res, next));
+    if (opts.mcp !== false) {
+        app.post('/mcp', mcpHttpHandler((req) => {
+            const caller = req.res?.locals.caller;
+            return {
+                name: api.tree.name,
+                version: opts.version,
+                instructions: api.tree.description || undefined,
+                tools: caller?.filter ? api.tools.filter((t) => allowed(t, caller.filter)) : api.tools,
+                cwd: opts.cwd,
+                timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder,
+                within: opts.within,
+                maxOutput: opts.maxOutput,
+                audit: opts.audit && ((entry) => opts.audit?.({ ...entry, key: caller?.name })),
+            };
+        }));
+    }
+    app.use(errorHandler);
+    return {
+        app,
+        queue,
+        /** The tree and tools being served now. */
+        current: () => ({ tree: api.tree, tools: api.tools }),
+        /** Stop watching (the app keeps serving the last set). */
+        close: () => watcher?.close(),
+    };
+}
+/** A POST with a non-JSON body: validate the query (or the args part), then run with the body as stdin. */
+async function runBody(opts, ctx, tool, req, res) {
+    const inputSchema = toJsonSchema(tool.schema);
+    const dir = mkdtempSync(join(tmpdir(), 'clyops-api-'));
+    let keep = false;
+    try {
+        let input;
+        let stdin;
+        if (req.is('multipart/form-data')) {
+            const parts = await readMultipart(req, tool, dir, ctx.maxBody);
+            input = parts.input;
+            stdin = parts.stdin;
+        }
+        else {
+            input = queryInput(req.query, inputSchema);
+            stdin = req;
+        }
+        const checked = toZod(inputSchema).safeParse(input);
+        if (!checked.success)
+            return void res.status(400).json({ error: 'Validation failed', issues: checked.error.issues });
+        if (req.query.async === 'true' && stdin === req) {
+            // A job runs later: keep the body until then.
+            stdin = join(dir, 'stdin');
+            await pipeline(req, limited(ctx.maxBody), createWriteStream(stdin));
+        }
+        keep = req.query.async === 'true';
+        await respond(opts, ctx, tool, input, req, res, stdin, keep ? dir : undefined);
+    }
+    finally {
+        if (!keep)
+            rmSync(dir, { recursive: true, force: true });
+    }
+}
+/**
+ * Run a tool for a request and answer: a job (`?async=true`), the raw
+ * stdout stream, or the JSON envelope. `stdin` is a file path (opened when
+ * the tool starts) or a stream. A job owns `dir` and removes it when dropped.
+ */
+async function respond(opts, ctx, tool, input, req, res, stdin, dir) {
+    const caller = res.locals.caller;
+    const base = { cwd: opts.cwd, timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder, within: opts.within, maxOutput: opts.maxOutput };
+    const open = () => (typeof stdin === 'string' ? createReadStream(stdin) : stdin);
+    const audit = (result) => opts.audit?.({
+        key: caller?.name, tool: tool.words.join(' '), command: result.command, exitCode: result.exitCode, signal: result.signal,
+        timedOut: result.timedOut, durationMs: result.durationMs, via: 'api',
+    });
+    if (req.query.async === 'true') {
+        const jobDir = dir ?? mkdtempSync(join(tmpdir(), 'clyops-api-'));
+        const toFile = streams(tool, req);
+        const job = ctx.queue.add(tool.words.join(' '), async ({ signal }) => {
+            let result;
+            if (toFile) {
+                const started = startTool(tool, input, { ...base, signal, stdin: open(), stdout: 'stream' });
+                const [r] = await Promise.all([started.result, pipeline(started.stdout, createWriteStream(join(jobDir, 'stdout')))]);
+                result = { ...r, ok: r.exitCode === 0 && !r.timedOut && !r.signal, stdoutUrl: `/jobs/${job.record.job_id}/stdout` };
+            }
+            else {
+                result = envelope(await runTool(tool, input, { ...base, signal, stdin: open(), stdout: binaryStdout(tool) ? 'buffer' : 'text' }));
+            }
+            audit(result);
+            return result;
+        }, caller?.name ? { key: caller.name } : {});
+        ctx.jobDirs.set(job.record.job_id, jobDir);
+        res.status(202).location(`/jobs/${job.record.job_id}`).json(job.record);
+        return;
+    }
+    // A client that goes away stops the tool.
+    const abort = new AbortController();
+    res.on('close', () => !res.writableEnded && abort.abort());
+    if (!streams(tool, req)) {
+        const result = await runTool(tool, input, { ...base, signal: abort.signal, stdin: open(), stdout: binaryStdout(tool) ? 'buffer' : 'text' });
+        audit(result);
+        res.json(envelope(result));
+        return;
+    }
+    // Stream stdout as it comes. The exit status isn't known when the headers
+    // go out, so it follows as a trailer; a failure before any output is still
+    // a JSON error.
+    const started = startTool(tool, input, { ...base, signal: abort.signal, stdin: open(), stdout: 'stream' });
+    const out = started.stdout;
+    const first = await new Promise((resolve) => {
+        out.once('data', (chunk) => {
+            out.pause();
+            resolve(chunk);
+        });
+        out.once('end', () => resolve(null));
+    });
+    if (!first) {
+        const result = await started.result;
+        audit(result);
+        if (result.exitCode !== 0)
+            return void res.status(500).json(envelope({ ...result, ok: false }));
+        res.status(200).type(binaryStdout(tool) ?? 'application/octet-stream').end();
+        return;
+    }
+    res.status(200);
+    res.setHeader('Content-Type', binaryStdout(tool) ?? 'application/octet-stream');
+    res.setHeader('Trailer', 'X-Clyops-Exit-Code, X-Clyops-Stderr');
+    res.write(first);
+    out.pipe(res, { end: false });
+    const [result] = await Promise.all([started.result, finished(out)]);
+    audit(result);
+    res.addTrailers({ 'X-Clyops-Exit-Code': String(result.exitCode ?? ''), 'X-Clyops-Stderr': stderrTrailer(result.stderr) });
+    res.end();
+}
+/**
+ * The OpenAPI document with what plus-express can't express: the other
+ * request bodies (a tool's stdin, multipart), the query parameters they take,
+ * declared binary stdout and the tools' effects.
+ */
+function documentStreams(doc, tools) {
+    const binary = { type: 'string', format: 'binary' };
+    for (const tool of tools) {
+        const op = doc.paths?.[tool.path]?.post;
+        if (!op)
+            continue;
+        if (tool.schema.effects?.length)
+            op['x-clyops-effects'] = tool.schema.effects;
+        const content = (op.requestBody ??= { content: {} }).content;
+        for (const type of tool.schema.stdin?.contentType ? tool.schema.stdin.contentType.split(',').map((t) => t.trim()) : ['application/octet-stream']) {
+            content[type] = { schema: { ...binary, description: `Standard input${tool.schema.stdin?.description ? `: ${tool.schema.stdin.description}` : ''}; the arguments come from the query string` } };
+        }
+        content['multipart/form-data'] = {
+            schema: {
+                type: 'object',
+                properties: { args: { type: 'string', description: 'The input, as JSON' }, stdin: { ...binary, description: 'Standard input' } },
+                additionalProperties: { ...binary, description: 'A file for the path input of the same name' },
+            },
+        };
+        const properties = (toJsonSchema(tool.schema).properties ?? {});
+        op.parameters = [
+            ...(op.parameters ?? []),
+            ...Object.entries(properties).map(([name, schema]) => ({
+                in: 'query', name, required: false, schema, ...(schema.type === 'array' ? { style: 'form', explode: true } : {}),
+                description: `${schema.description ?? ''} (with a non-JSON body)`.trim(),
+            })),
+        ];
+        const type = binaryStdout(tool);
+        const ok = op.responses?.['200'];
+        if (type && ok)
+            ok.content = { [type]: { schema: { ...binary, description: tool.schema.stdout?.description ?? '' } }, ...ok.content };
+    }
+    return doc;
+}
+/** The documented routes for one set of tools, on their own router and registry. */
+function buildRoutes(opts, ctx, tree, tools) {
+    const { queue } = ctx;
+    const { router, registry } = plus(express.Router(), {
+        openApiConfig: {
+            openapi: '3.0.0',
+            info: { title: tree.name, version: opts.version ?? '0.0.0', description: tree.description || `clyops tools in ${tree.dir}` },
+        },
+    });
+    if (opts.apiKey || Object.keys(opts.keys ?? {}).length)
+        registry.registerSecurityScheme('apiKey', { type: 'http', scheme: 'bearer' });
+    const jobView = (record, result) => ({ ...record, ...(result ? { result } : {}) });
+    const visible = (res) => {
+        const caller = res.locals.caller;
+        return {
+            tool: (t) => !caller?.filter || allowed(t, caller.filter),
+            // With named keys, a key sees only its own jobs.
+            job: (r) => !caller?.name || r.key === caller.name,
+        };
+    };
+    router.get({
+        path: '/tools',
+        summary: 'List the tools',
+        tags: ['tools'],
+        responses: { 200: json(z.array(z.object({ name: z.string(), words: z.array(z.string()), path: z.string(), description: z.string() })), 'The tools') },
+    }, (_req, res) => {
+        res.json(tools.filter(visible(res).tool).map((t) => ({ name: t.name, words: t.words, path: t.path, description: t.description })));
+    });
+    for (const tool of tools) {
+        const inputSchema = toJsonSchema(tool.schema);
+        const tag = tool.words.length > 1 ? tool.words.slice(0, -1).join(' ') : 'tools';
+        router.get({
+            path: tool.path,
+            summary: `Describe ${tool.words.join(' ')}`,
+            tags: [tag],
+            responses: { 200: json(z.object({ schema: z.unknown(), input: z.unknown() }), 'The tool\'s clyops schema and the JSON Schema of its input') },
+        }, (_req, res) => {
+            res.json({ schema: tool.schema, input: inputSchema });
+        });
+        router.post({
+            path: tool.path,
+            operationId: tool.words.join('_').replace(/[^A-Za-z0-9_]/g, '_'),
+            summary: tool.description || tool.words.join(' '),
+            description: [tool.schema.description, tool.schema.epilog].filter(Boolean).join('\n\n'),
+            tags: [tag],
+            body: toZod(inputSchema),
+            query: z.object({ async: z.enum(['true', 'false']).optional().openapi({ description: 'Return a job id at once instead of waiting' }) }),
+            responses: {
+                200: json(RunResponseSchema, 'The tool ran; `ok` is false when it exited non-zero'),
+                202: json(JobSchema, 'Queued (with `?async=true`); poll `GET /jobs/{id}`'),
+                400: json(ErrorSchema, 'Invalid input'),
+                403: json(ErrorSchema, 'The API key may not run this tool'),
+                500: json(RunResponseSchema, 'Streaming output: the tool failed before writing any'),
+            },
+        }, async (req, res, next) => {
+            try {
+                await respond(opts, ctx, tool, (req.body ?? {}), req, res);
+            }
+            catch (err) {
+                next(err);
+            }
+        });
+    }
+    const JobParams = z.object({ id: z.string() });
+    const find = (req, res) => {
+        const job = queue.get(String(req.params.id));
+        return job && visible(res).job(job.record) ? job : undefined;
+    };
+    router.get({ path: '/jobs', summary: 'List jobs', tags: ['jobs'], responses: { 200: json(z.array(JobSchema), 'Recent jobs, without results') } }, (_req, res) => {
+        res.json(queue.list().filter(visible(res).job));
+    });
+    router.get({ path: '/jobs/:id', summary: 'A job, with its result once done', tags: ['jobs'], params: JobParams, responses: { 200: json(JobSchema, 'The job'), 404: json(ErrorSchema, 'No such job') } }, (req, res) => {
+        const job = find(req, res);
+        if (!job)
+            return void res.status(404).json({ error: `no job ${req.params.id}` });
+        res.json(jobView(job.record, job.result));
+    });
+    router.get({
+        path: '/jobs/:id/stdout',
+        summary: 'A finished job\'s binary output',
+        tags: ['jobs'],
+        params: JobParams,
+        responses: {
+            200: { description: 'The output, with the tool\'s declared content type', content: { 'application/octet-stream': { schema: z.string().openapi({ format: 'binary' }) } } },
+            404: json(ErrorSchema, 'No such job, or no output (yet)'),
+        },
+    }, (req, res) => {
+        const job = find(req, res);
+        const file = job && ctx.jobDirs.get(job.record.job_id) && join(ctx.jobDirs.get(job.record.job_id), 'stdout');
+        if (!job || !file || job.record.status !== 'done' || !existsSync(file))
+            return void res.status(404).json({ error: `no output for job ${req.params.id}` });
+        const tool = tools.find((t) => t.words.join(' ') === job.record.function);
+        res.type((tool && binaryStdout(tool)) ?? 'application/octet-stream').sendFile(file);
+    });
+    router.delete({ path: '/jobs/:id', summary: 'Cancel a job', tags: ['jobs'], params: JobParams, responses: { 202: json(JobSchema, 'Cancelling'), 404: json(ErrorSchema, 'No such job') } }, (req, res) => {
+        const job = find(req, res);
+        if (!job)
+            return void res.status(404).json({ error: `no job ${req.params.id}` });
+        job.cancel();
+        res.status(202).json(jobView(job.record));
+    });
+    return { router, registry, tree, tools };
+}
+/** Errors as JSON: validation failures (400) with zod's issues, anything else 500. */
+export function errorHandler(err, _req, res, _next) {
+    const status = err.status ?? 500;
+    let issues = err.errors;
+    if (typeof issues === 'string') {
+        try {
+            issues = JSON.parse(issues);
+        }
+        catch {
+            // plain message
+        }
+    }
+    if (res.headersSent)
+        return void res.end();
+    res.status(status).json({ error: err.message, ...(issues !== undefined ? { issues } : {}) });
+}

package/dist/zod.d.ts

@@ -0,0 +1,28 @@
+import type { JsonSchema } from 'clyops-tools';
+import { z } from 'plus-express';
+type Js = JsonSchema & {
+    type?: string;
+    enum?: string[];
+    pattern?: string;
+    items?: Js;
+    description?: string;
+    default?: unknown;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    properties?: Record<string, Js>;
+    required?: string[];
+    allOf?: {
+        not?: {
+            required?: string[];
+            properties?: Record<string, Js & {
+                const?: unknown;
+                not?: unknown;
+            }>;
+        };
+        description?: string;
+    }[];
+};
+export declare function toZod(schema: Js): z.ZodType;
+export {};

package/dist/zod.js

@@ -0,0 +1,75 @@
+import { z } from 'plus-express';
+/** Whether `value` matches one of the "given" shapes toJsonSchema uses for exclusive options. */
+function given(value, shape) {
+    if (value === undefined || value === null)
+        return false;
+    if (!shape)
+        return true;
+    if ('const' in shape)
+        return value === shape.const;
+    if (shape.type === 'array')
+        return Array.isArray(value) && value.length >= (shape.minItems ?? 0);
+    return true;
+}
+export function toZod(schema) {
+    let out;
+    switch (schema.type) {
+        case 'integer':
+        case 'number': {
+            let n = schema.type === 'integer' ? z.number().int() : z.number();
+            if (schema.minimum !== undefined)
+                n = n.min(schema.minimum);
+            if (schema.maximum !== undefined)
+                n = n.max(schema.maximum);
+            out = n;
+            break;
+        }
+        case 'boolean':
+            out = z.boolean();
+            break;
+        case 'array':
+            out = z.array(toZod(schema.items ?? {}));
+            break;
+        case 'object': {
+            const required = new Set(schema.required ?? []);
+            const shape = Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, prop]) => [key, required.has(key) ? toZod(prop) : toZod(prop).optional()]));
+            out = z.strictObject(shape);
+            // Exclusive options (allOf: [{ not: { required: [a, b] } }]) can't both be given.
+            const exclusive = (schema.allOf ?? []).filter((c) => c.not?.required?.length);
+            if (exclusive.length) {
+                out = out.superRefine((value, ctx) => {
+                    const input = value;
+                    for (const c of exclusive) {
+                        const keys = c.not?.required ?? [];
+                        if (keys.every((k) => given(input[k], c.not?.properties?.[k]))) {
+                            ctx.addIssue({ code: z.ZodIssueCode.custom, path: [keys[keys.length - 1]], message: c.description ?? `${keys.join(' and ')} cannot be used together` });
+                        }
+                    }
+                });
+            }
+            break;
+        }
+        default: {
+            if (schema.enum) {
+                out = z.enum(schema.enum);
+                break;
+            }
+            let s = z.string();
+            if (schema.minLength !== undefined)
+                s = s.min(schema.minLength);
+            if (schema.maxLength !== undefined)
+                s = s.max(schema.maxLength);
+            if (schema.pattern)
+                s = s.regex(new RegExp(schema.pattern));
+            out = s;
+        }
+    }
+    // Defaults are documentation only: the tool applies its own, so a value it
+    // would get from its config file or environment is not overridden.
+    const meta = {};
+    if (schema.description)
+        meta.description = schema.description;
+    if (schema.default !== undefined)
+        meta.default = schema.default;
+    return Object.keys(meta).length ? out.openapi(meta) : out;
+}

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "clyops-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Serve a directory of clyops tools as an HTTP API: an endpoint per tool, validated and documented in OpenAPI from its schema, with sync and async (job) runs.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wankdanker/clyops.git",
+    "directory": "apps/api"
+  },
+  "keywords": [
+    "clyops",
+    "api",
+    "openapi",
+    "express",
+    "cli",
+    "tools"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "bin": {
+    "clyops-api": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "busboy": "^1.6.0",
+    "clyops": "0.3.0",
+    "clyops-jobs": "0.3.0",
+    "clyops-mcp": "0.3.0",
+    "clyops-tools": "0.3.0",
+    "express": "^5.2.1",
+    "plus-express": "^2.1.1"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "@types/busboy": "^1.5.4",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs"
+  }
 }