@thenavidm/slipway 0.1.0

package/dist/app.js

@@ -0,0 +1,364 @@
+/**
+ * An app: one service, its tools, and the single path every call takes.
+ *
+ * The MCP server and the CLI are thin. Both hand a tool and its arguments to
+ * `run`, which applies visibility, the write guard, timeouts, cancellation and
+ * redaction in one place. A rule added here holds on both surfaces at once,
+ * which is why the two cannot drift.
+ */
+import { basename } from "node:path";
+import { CanceledError, NotConfiguredError, RefusedError, SlipwayError, TimeoutError, UsageError, toSlipwayError, } from "./errors.js";
+import * as z from "zod";
+import { cacheKey, dataDir, scopeOf, storeAt } from "./data.js";
+import { Guard } from "./guard.js";
+import { isBackground, JobRegistry, runJob, waitSecondsFor } from "./jobs.js";
+import { policyEnvNames, readPolicy, visibility } from "./policy.js";
+import { Secrets } from "./redact.js";
+import { isContentResult } from "./result.js";
+import { formatIssues, validate } from "./schema.js";
+import { buildServer } from "./server.js";
+import { localDataTools } from "./sync.js";
+import { defineTool, isTool, summarize } from "./tool.js";
+const SLUG = /^[a-z][a-z0-9-]{0,40}$/;
+export function stderrLogger(prefix, env) {
+    const debug = /^(1|true|yes)$/i.test(env[`${prefix}_DEBUG`] ?? "");
+    const write = (level, message, data) => process.stderr.write(`[${prefix.toLowerCase()}] ${level} ${message}${data === undefined ? "" : ` ${JSON.stringify(data)}`}\n`);
+    return {
+        debug: (message, data) => {
+            if (debug)
+                write("debug", message, data);
+        },
+        info: (message, data) => write("info", message, data),
+        warn: (message, data) => write("warn", message, data),
+        error: (message, data) => write("error", message, data),
+    };
+}
+/** Create an app. Throws at load time on duplicate tools or a name that cannot become two binaries. */
+export function slipway(definition) {
+    if (!SLUG.test(definition.name ?? "")) {
+        throw new Error(`App name '${definition.name}' must be a lowercase slug, like 'bluesky' or 'google-photos'.`);
+    }
+    if (!definition.version)
+        throw new Error(`App '${definition.name}': version is required.`);
+    for (const tool of definition.tools) {
+        if (!isTool(tool))
+            throw new Error(`App '${definition.name}': every entry in tools must come from defineTool.`);
+    }
+    // A synced list brings the tools that search and refresh local data. `app`
+    // is read when they run, after it exists.
+    const synced = definition.tools.filter((tool) => tool.sync);
+    const local = synced.length ? localDataTools(synced, () => app) : [];
+    // Each job tool brings the tool that checks on its jobs, right after it.
+    const allTools = [...definition.tools, ...local].flatMap((tool) => (tool.job && !tool.statusOf ? [tool, statusToolFor(tool)] : [tool]));
+    const caches = allTools.some((tool) => tool.cache);
+    const seen = new Set();
+    for (const tool of allTools) {
+        if (seen.has(tool.name)) {
+            throw new Error(`App '${definition.name}': two tools are named '${tool.name}'${tool.statusOf ? `, and Slipway names the status tool of ${tool.statusOf} that` : ""}.`);
+        }
+        seen.add(tool.name);
+    }
+    const jobs = new JobRegistry();
+    const envPrefix = definition.envPrefix ?? definition.name.toUpperCase().replace(/-/g, "_");
+    const bins = { mcp: definition.bins?.mcp ?? `${definition.name}-mcp`, cli: definition.bins?.cli ?? `${definition.name}-cli` };
+    const secrets = new Secrets();
+    const contexts = new WeakMap();
+    const byName = new Map();
+    for (const tool of allTools) {
+        byName.set(tool.name, tool);
+        byName.set(tool.command, tool);
+    }
+    const app = {
+        kind: "slipway.app",
+        name: definition.name,
+        title: definition.title ?? definition.name,
+        version: definition.version,
+        description: definition.description,
+        instructions: definition.instructions,
+        envPrefix,
+        bins,
+        definition,
+        allTools,
+        secrets,
+        policy(env = process.env) {
+            return readPolicy(env, envPrefix, definition.defaults);
+        },
+        tools(env = process.env) {
+            const policy = app.policy(env);
+            return allTools.filter((tool) => visibility(tool, policy).visible);
+        },
+        find(nameOrCommand) {
+            return byName.get(nameOrCommand) ?? byName.get(nameOrCommand.replace(/-/g, "_"));
+        },
+        context(env = process.env) {
+            let pending = contexts.get(env);
+            if (!pending) {
+                pending = (async () => {
+                    let ctx;
+                    try {
+                        ctx = await definition.context(env);
+                    }
+                    catch (error) {
+                        // A context that cannot be built is a setup problem, so it gets the
+                        // setup exit code and points at doctor, whatever threw it.
+                        const known = error instanceof SlipwayError ? error : undefined;
+                        throw (known ??
+                            new NotConfiguredError(error?.message ?? String(error), {
+                                hint: `Run \`${bins.cli} doctor\` to see what is missing.`,
+                                cause: error,
+                            }));
+                    }
+                    secrets.add(...(definition.secrets?.(ctx) ?? []));
+                    return ctx;
+                })();
+                // A failed build is not cached, so fixing the environment and retrying works in a long-lived server.
+                pending.catch(() => contexts.delete(env));
+                contexts.set(env, pending);
+            }
+            return pending;
+        },
+        async invoke(nameOrCommand, args, options) {
+            const tool = app.find(nameOrCommand);
+            if (!tool) {
+                throw new UsageError(`Unknown tool '${nameOrCommand}'.`, { hint: `Run \`${bins.cli}\` to list the tools.` });
+            }
+            return app.run(tool, await app.parse(tool, args), options);
+        },
+        async parse(tool, args) {
+            const checked = await validate(tool.schema, args ?? {});
+            if (!checked.ok) {
+                throw new UsageError(`Invalid arguments for ${tool.name}: ${formatIssues(checked.issues)}`, {
+                    hint: `Run \`${bins.cli} ${tool.command} --help\` for what it takes.`,
+                    details: checked.issues,
+                });
+            }
+            return checked.value;
+        },
+        preflight(tool, rawArgs, options) {
+            const env = options.env ?? process.env;
+            const policy = app.policy(env);
+            assertVisible(tool, policy, envPrefix);
+            const { confirm: _confirm, ...args } = rawArgs;
+            const summary = summarize(tool, args);
+            new Guard(policy, options.surface, envPrefix).preflight(tool, summary);
+            return summary;
+        },
+        async run(tool, rawArgs, options) {
+            const env = options.env ?? process.env;
+            const policy = app.policy(env);
+            assertVisible(tool, policy, envPrefix);
+            // Slipway's own arguments are not the tool's, so the handler never sees them.
+            const { confirm, wait_seconds: waitSeconds, ...args } = rawArgs;
+            const confirmedBy = options.approvedBy ?? (options.confirmed === true || confirm === true ? "flag" : undefined);
+            const dryRun = options.dryRun === true;
+            const summary = summarize(tool, args);
+            const guard = new Guard(policy, options.surface, envPrefix);
+            guard.check(tool, { confirmedBy, dryRun, summary });
+            const ctx = await app.context(env);
+            const timeoutMs = tool.timeoutMs ?? policy.toolTimeoutMs;
+            const withDeadline = () => deadlineSignal(options.signal, timeoutMs);
+            const signal = withDeadline();
+            const log = options.log ?? stderrLogger(envPrefix, env);
+            const callProgress = increasing(options.onProgress);
+            // The app's own context stays the prototype, so a class instance keeps its
+            // methods and getters, and Slipway's fields sit on top.
+            const contextWith = (runSignal, report) => {
+                const runContext = {
+                    signal: runSignal,
+                    surface: options.surface,
+                    env,
+                    dryRun,
+                    tool: { name: tool.name, risk: tool.risk },
+                    secrets,
+                    log,
+                    async progress(progress, total, message) {
+                        report({ progress, ...(total === undefined ? {} : { total }), ...(message ? { message } : {}) });
+                    },
+                };
+                return Object.assign(Object.create(ctx), runContext);
+            };
+            const toolContext = contextWith(signal, callProgress);
+            if (dryRun) {
+                const wouldRun = tool.preview ? await tool.preview(args, toolContext) : args;
+                return { dry_run: true, tool: tool.name, summary, would_run: secrets.redactDeep(wouldRun) };
+            }
+            const writes = tool.risk !== "read" || tool.requireConfirm;
+            const cache = tool.cache && policy.cache ? { scope: app.dataScope(ctx), key: cacheKey(args), ttlSeconds: tool.cache.ttlSeconds } : undefined;
+            if (cache && !options.refresh) {
+                const hit = await quietly(log, async () => (await app.localData(env)).cacheGet(cache.scope, tool.name, cache.key));
+                if (hit) {
+                    options.onCache?.({ ageSeconds: Math.max(0, Math.round((Date.now() - hit.storedAt) / 1000)) });
+                    return hit.value;
+                }
+            }
+            // A write may change anything a cached read returned, even one that failed partway.
+            const forget = async () => {
+                if (writes && caches && policy.cache)
+                    await quietly(log, async () => (await app.localData(env)).cacheClear(app.dataScope(ctx)));
+            };
+            try {
+                let result;
+                const jobTool = tool.statusOf ? byName.get(tool.statusOf) : tool;
+                if (jobTool?.job) {
+                    const statusTool = tool.statusOf ? tool : allTools.find((candidate) => candidate.statusOf === tool.name);
+                    // A background job in a terminal ends with the command, so the command waits for it.
+                    const waitMs = options.waitMs ??
+                        (options.surface === "cli" && isBackground(jobTool.job) ? Number.POSITIVE_INFINITY : (typeof waitSeconds === "number" ? waitSeconds : waitSecondsFor(jobTool.job)) * 1000);
+                    result = await runJob({
+                        jobTool: jobTool.name,
+                        job: jobTool.job,
+                        ...(tool.statusOf ? { jobId: String(args.job_id) } : { start: (runCtx) => jobTool.handler(args, runCtx) }),
+                        waitMs,
+                        waitSignal: options.signal,
+                        requestSignal: withDeadline,
+                        context: contextWith,
+                        progress: callProgress,
+                        registry: jobs,
+                        timeoutMs: jobTool.timeoutMs,
+                        check: (id) => options.surface === "cli"
+                            ? `${bins.cli} ${statusTool.command} ${id} --wait`
+                            : policy.surface === "search"
+                                ? `Call call_tool with name "${statusTool.name}" and arguments {"job_id": "${id}"} to check on it. Add wait_seconds to wait for it to finish.`
+                                : `Call ${statusTool.name} with job_id "${id}" to check on it. Pass wait_seconds to wait for it to finish.`,
+                        untilAborted: (work, runSignal) => untilAborted(work, runSignal, timeoutMs, tool.name),
+                    });
+                }
+                else {
+                    result = await untilAborted(Promise.resolve(tool.handler(args, toolContext)), signal, timeoutMs, tool.name);
+                }
+                if (writes)
+                    guard.record(tool, summary, result?.done === false ? "started" : "done");
+                await forget();
+                // Only data is cached. Images and files are fetched again.
+                if (cache && !isContentResult(result)) {
+                    const stored = secrets.redactDeep(result);
+                    await quietly(log, async () => (await app.localData(env)).cachePut(cache.scope, tool.name, cache.key, stored, cache.ttlSeconds));
+                }
+                return result;
+            }
+            catch (error) {
+                if (writes)
+                    guard.record(tool, summary, "failed");
+                await forget();
+                throw toSlipwayError(error);
+            }
+        },
+        localData(env = process.env) {
+            return storeAt(dataDir(definition.name, envPrefix, env));
+        },
+        dataScope(ctx) {
+            return scopeOf(definition.secrets?.(ctx) ?? [], definition.dataScope?.(ctx));
+        },
+        createServer(env = process.env) {
+            return buildServer(app, env);
+        },
+        async runCli(argv, io) {
+            const { runCli } = await import("./cli/run.js");
+            return runCli(app, argv, io);
+        },
+        async main(argv = process.argv.slice(2)) {
+            const { main } = await import("./entry.js");
+            await main(app, argv, basename(process.argv[1] ?? ""));
+        },
+    };
+    return app;
+}
+/** Local data helps a call but never fails one: anything that goes wrong with it is a cache miss, logged for debugging. */
+async function quietly(log, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        log.debug("local data unavailable", { error: error?.message ?? String(error) });
+        return undefined;
+    }
+}
+/** The caller's cancel and the tool's deadline as one signal, new for each request so every request gets the full time. */
+function deadlineSignal(signal, timeoutMs) {
+    const signals = [];
+    if (signal)
+        signals.push(signal);
+    if (timeoutMs)
+        signals.push(AbortSignal.timeout(timeoutMs));
+    return signals.length === 0 ? new AbortController().signal : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+}
+/**
+ * Progress for one caller. The protocol requires each update to be larger than
+ * the last, so a handler that repeats a value, or a job reporting to a second
+ * caller, would otherwise get the call rejected by a strict client.
+ */
+function increasing(onProgress) {
+    let last = -Infinity;
+    return (update) => {
+        if (!onProgress || update.progress <= last)
+            return;
+        last = update.progress;
+        void Promise.resolve(onProgress(update)).catch(() => undefined);
+    };
+}
+/** The tool that checks on a job tool's jobs. It reads, whatever the job tool does. */
+function statusToolFor(tool) {
+    const input = z.object({ job_id: z.string().min(1).describe(`The job_id ${tool.name} returned.`) });
+    const status = defineTool({
+        name: `${tool.name}_status`,
+        title: `${tool.title}: status`,
+        description: `Check on a job ${tool.name} started: whether it is still running, and its result once it is done. Pass wait_seconds to wait for it to finish.`,
+        input,
+        risk: "read",
+        openWorld: tool.openWorld,
+        tags: [...tool.tags],
+        positional: ["job_id"],
+        job: tool.job,
+        examples: [],
+        handler: () => {
+            throw new Error(`${tool.name}_status runs through its job, never on its own.`);
+        },
+    });
+    return Object.freeze({ ...status, statusOf: tool.name });
+}
+/** A hidden tool is refused with the setting that hides it, so the refusal says how to turn it on. */
+function assertVisible(tool, policy, envPrefix) {
+    const seen = visibility(tool, policy);
+    if (seen.visible)
+        return;
+    const names = policyEnvNames(envPrefix);
+    if (seen.reason === "read-only") {
+        throw new RefusedError(`${tool.name} is unavailable: this server is running with ${names.readOnly}=1.`, {
+            hint: `Unset ${names.readOnly} to allow writes.`,
+        });
+    }
+    throw new UsageError(`${tool.name} is in a toolset that is off: ${tool.tags.join(", ")}.`, {
+        hint: `Add one of them to ${names.toolsets}, or set ${names.toolsets}=all.`,
+    });
+}
+/**
+ * Race a handler against its abort signal.
+ *
+ * A handler that ignores the signal cannot be stopped, but its caller can stop
+ * waiting for it: a client that canceled, or a call past its deadline, gets an
+ * answer now rather than when the upstream API finally gives up.
+ */
+function untilAborted(work, signal, timeoutMs, name) {
+    if (signal.aborted)
+        return Promise.reject(abortError(signal, timeoutMs, name));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError(signal, timeoutMs, name));
+        signal.addEventListener("abort", onAbort, { once: true });
+        work.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
+function abortError(signal, timeoutMs, name) {
+    const reason = signal.reason;
+    if (reason?.name === "TimeoutError") {
+        return new TimeoutError(`${name} did not finish within ${timeoutMs} ms.`, {
+            hint: "Narrow the request, or raise the tool timeout if the upstream API is genuinely slow.",
+        });
+    }
+    return new CanceledError(`${name} was canceled.`);
+}

package/dist/bin.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * The `slipway` command, for people building on Slipway.
+ *
+ *   slipway check [module]    the release gate: schemas, parity, docs, startup
+ *   slipway docs [module]     the command and argument reference, as Markdown
+ *   slipway inspect [module]  what an MCP client receives
+ *   slipway openapi <doc>     the tools an OpenAPI document becomes, and its pin
+ *
+ * `module` is the built file that exports the app, `dist/app.js` by default.
+ * It must only export the app: the file that calls `app.main()` would start a
+ * server the moment it was imported.
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env node
+/**
+ * The `slipway` command, for people building on Slipway.
+ *
+ *   slipway check [module]    the release gate: schemas, parity, docs, startup
+ *   slipway docs [module]     the command and argument reference, as Markdown
+ *   slipway inspect [module]  what an MCP client receives
+ *   slipway openapi <doc>     the tools an OpenAPI document becomes, and its pin
+ *
+ * `module` is the built file that exports the app, `dist/app.js` by default.
+ * It must only export the app: the file that calls `app.main()` would start a
+ * server the moment it was imported.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { checkApp } from "./check.js";
+import { SLIPWAY_VERSION } from "./cli/context.js";
+import { renderDocs } from "./docs.js";
+import { fromOpenAPI, openapiHash, readOperations } from "./openapi.js";
+import { connectInMemory } from "./rpc.js";
+const HELP = `slipway ${SLIPWAY_VERSION}
+
+  slipway check [module] [--bin <entry>] [--docs a.md,b.md] [--json] [--strict]
+      Check an app before release: names, descriptions, schema validity and
+      size, examples, MCP and CLI parity, the commands your docs mention, and
+      (with --bin) that the built server starts with nothing configured.
+
+  slipway docs [module]
+      Print the command and argument reference as Markdown.
+
+  slipway inspect [module] [--json]
+      List the tools exactly as an MCP client receives them.
+
+  slipway openapi <file|url> [--json]
+      Show the tools an OpenAPI 3 document becomes: names, risk, toolsets,
+      what is skipped and why, and the sha256 to pin it with.
+
+  module defaults to dist/app.js, a file that exports the app and does not start it.
+`;
+function option(argv, name) {
+    const at = argv.findIndex((token) => token === name || token.startsWith(`${name}=`));
+    if (at === -1)
+        return undefined;
+    return argv[at].includes("=") ? argv[at].split("=").slice(1).join("=") : argv[at + 1];
+}
+async function loadApp(path) {
+    const file = resolve(path ?? "dist/app.js");
+    if (!existsSync(file)) {
+        throw new Error(`${file} does not exist. Build first, or pass the module that exports your app.`);
+    }
+    const module = (await import(pathToFileURL(file).href));
+    const app = [module.default, module.app, ...Object.values(module)].find((value) => value?.kind === "slipway.app");
+    if (!app)
+        throw new Error(`${file} exports no Slipway app. Export the value slipway({...}) returns.`);
+    return app;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    const positional = rest.filter((token, i) => !token.startsWith("--") && !["--bin", "--docs"].includes(rest[i - 1] ?? ""))[0];
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (command === "--version" || command === "-v" || command === "version") {
+        process.stdout.write(`${SLIPWAY_VERSION}\n`);
+        return 0;
+    }
+    if (command === "openapi") {
+        if (!positional)
+            throw new Error("openapi expects a document: slipway openapi openapi.json");
+        return openapiPreview(positional, rest.includes("--json"));
+    }
+    const app = await loadApp(positional);
+    if (command === "docs") {
+        process.stdout.write(renderDocs(app, process.env));
+        return 0;
+    }
+    if (command === "inspect") {
+        const client = await connectInMemory(app, process.env);
+        const tools = await client.listTools();
+        await client.close();
+        if (rest.includes("--json"))
+            process.stdout.write(`${JSON.stringify({ initialize: client.initialize, tools }, null, 2)}\n`);
+        else {
+            process.stdout.write(`${client.initialize.serverInfo.name} ${client.initialize.serverInfo.version}, protocol ${client.initialize.protocolVersion}, ${tools.length} tools\n\n`);
+            for (const tool of tools) {
+                const a = tool.annotations ?? {};
+                const mark = a.readOnlyHint ? " " : a.destructiveHint ? "!" : "*";
+                process.stdout.write(`  ${mark} ${tool.name}  ${Math.round(JSON.stringify(tool).length / 102.4) / 10} KB${tool.outputSchema ? "  typed" : ""}\n`);
+            }
+        }
+        return 0;
+    }
+    if (command === "check") {
+        const docs = option(rest, "--docs")?.split(",").filter(Boolean);
+        const bin = option(rest, "--bin");
+        const report = await checkApp(app, { env: process.env, ...(docs ? { docs } : {}), ...(bin ? { bin: resolve(bin) } : {}) });
+        const strict = rest.includes("--strict");
+        const failed = report.errors > 0 || (strict && report.warnings > 0);
+        if (rest.includes("--json")) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            return failed ? 1 : 0;
+        }
+        const s = report.stats;
+        process.stdout.write(`\n${app.title} ${app.version}: ${s.tools === s.allTools ? `${s.tools} tools` : `${s.tools} of ${s.allTools} tools on`} (${s.reads} read, ${s.writes} write, ${s.irreversible} irreversible, ${s.confirmed} confirmed, ${s.typedOutput} typed)\n` +
+            `Schemas: ${Math.round(s.schemaBytes / 1024)} KB across all ${s.allTools} tools${s.largestTool ? `, largest ${s.largestTool.name} at ${Math.round(s.largestTool.bytes / 1024)} KB` : ""}` +
+            `${s.startupMs !== undefined ? `. Answered initialize in ${s.startupMs} ms with nothing configured` : ""}.\n\n`);
+        for (const finding of report.findings) {
+            process.stdout.write(`  ${finding.level === "error" ? "✗" : "!"} [${finding.check}]${finding.tool ? ` ${finding.tool}:` : ""} ${finding.message}\n`);
+        }
+        process.stdout.write(`\n${report.errors} errors, ${report.warnings} warnings. ${failed ? "Not ready." : "Ready."}\n`);
+        return failed ? 1 : 0;
+    }
+    process.stderr.write(`Unknown command '${command}'.\n\n${HELP}`);
+    return 2;
+}
+/** Read a document from a file or a URL, as JSON, or as YAML when the yaml package is installed. */
+async function readDocument(source) {
+    const text = /^https?:\/\//.test(source)
+        ? await fetch(source).then((response) => {
+            if (!response.ok)
+                throw new Error(`${source} answered ${response.status}.`);
+            return response.text();
+        })
+        : readFileSync(resolve(source), "utf8");
+    if (/^\s*[{[]/.test(text))
+        return JSON.parse(text);
+    try {
+        const yaml = (await import("yaml"));
+        return yaml.parse(text);
+    }
+    catch (error) {
+        if (error?.code === "ERR_MODULE_NOT_FOUND")
+            throw new Error("This document is YAML. Install the yaml package (npm install --save-dev yaml), or convert it to JSON.");
+        throw error;
+    }
+}
+async function openapiPreview(source, json) {
+    const document = await readDocument(source);
+    const { operations, skipped } = readOperations(document);
+    const tools = fromOpenAPI(document, { execute: () => undefined });
+    const sha256 = openapiHash(document);
+    const rows = tools.map((tool, i) => ({
+        tool: tool.name,
+        operation: `${operations[i].method} ${operations[i].path}`,
+        risk: tool.risk,
+        toolsets: tool.tags,
+        schema_kb: Math.round(JSON.stringify(tool.jsonSchema).length / 102.4) / 10,
+    }));
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ tools: rows, skipped, pin: { sha256 } }, null, 2)}\n`);
+        return 0;
+    }
+    const info = document.info;
+    const width = Math.max(4, ...rows.map((row) => row.tool.length)) + 2;
+    process.stdout.write(`\n${info?.title ?? "API"} ${info?.version ?? ""}: ${tools.length} tools from ${operations.length + skipped.length} operations\n\n`);
+    for (const row of rows) {
+        const mark = row.risk === "read" ? " " : row.risk === "destructive" ? "!" : "*";
+        process.stdout.write(`  ${mark} ${row.tool.padEnd(width)}${row.operation}${row.toolsets.length ? `  [${row.toolsets.join(", ")}]` : ""}${row.schema_kb > 16 ? `  ${row.schema_kb} KB` : ""}\n`);
+    }
+    if (skipped.length) {
+        process.stdout.write(`\nSkipped:\n`);
+        for (const item of skipped)
+            process.stdout.write(`  ${item.method} ${item.path}: ${item.reason}\n`);
+    }
+    const large = rows.filter((row) => row.schema_kb > 16).length;
+    if (large)
+        process.stdout.write(`\n${large} ${large === 1 ? "schema is" : "schemas are"} over 16 KB, which a model pays for each time it loads the tool. Leave such operations out with include, or offer the tools through ${"<PREFIX>"}_SURFACE=search.\n`);
+    process.stdout.write(`\n  * writes    ! public or irreversible\n\nPin this document in fromOpenAPI:\n  pin: { sha256: "${sha256}" }\n\n`);
+    return 0;
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`slipway: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/dist/check.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `slipway check`: the release gate.
+ *
+ * Unit tests prove a handler works. They do not prove that what a client
+ * receives matches what the CLI offers, that a schema will be accepted, that an
+ * example in the README still runs, or that the server answers when nothing is
+ * configured. Those are the failures that reach users, so they are checked here,
+ * against the real server, over the real protocol.
+ */
+import type { App } from "./app.js";
+export type Finding = {
+    level: "error" | "warn";
+    check: string;
+    tool?: string;
+    message: string;
+};
+export type CheckOptions = {
+    env?: NodeJS.ProcessEnv;
+    /** Markdown files whose commands and flags must exist: README.md, SKILL.md. */
+    docs?: string[];
+    /** The built entry point, to check it starts and answers with nothing configured. */
+    bin?: string;
+    /** Advertised schema size per tool that earns a warning, and an error. */
+    schemaBudget?: {
+        warnBytes: number;
+        errorBytes: number;
+    };
+};
+export type CheckReport = {
+    ok: boolean;
+    errors: number;
+    warnings: number;
+    findings: Finding[];
+    stats: {
+        /** Tools on under this environment. */
+        tools: number;
+        /** Every tool the app defines, whatever the environment turns on. Schema sizes cover all of them. */
+        allTools: number;
+        reads: number;
+        writes: number;
+        irreversible: number;
+        confirmed: number;
+        typedOutput: number;
+        schemaBytes: number;
+        largestTool?: {
+            name: string;
+            bytes: number;
+        };
+        startupMs?: number;
+    };
+};
+export declare function checkApp(app: App, options?: CheckOptions): Promise<CheckReport>;