@vxnsin/inkan 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// inkan check | openapi | routes <entry>
+// Loads the module that builds your app (listen() stays quiet while it does)
+// and reads it, without opening a port.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { formatReport } from "./check.js";
+const HELP = `
+  印 inkan
+
+  inkan check   <entry> [--only <text>] [--json]   run every example against its contract
+  inkan openapi <entry> [-o <file>]                write the OpenAPI 3.1 document
+  inkan routes  <entry>                            list the routes
+
+  <entry> is the file that builds the app and exports it,
+  as \`export default app\` or \`export const app\`.
+  It may also export \`beforeEach\`, which check runs before every example.
+`;
+const args = process.argv.slice(2);
+const command = args.shift();
+const option = (...names) => {
+    const i = args.findIndex((a) => names.includes(a));
+    if (i < 0)
+        return undefined;
+    return args.splice(i, 2)[1];
+};
+const has = (name) => {
+    const i = args.indexOf(name);
+    if (i >= 0)
+        args.splice(i, 1);
+    return i >= 0;
+};
+function fail(msg) {
+    console.error(`\n  inkan: ${msg}\n`);
+    process.exit(2);
+}
+async function load(entry) {
+    if (!entry)
+        fail("Which file builds the app? For example: inkan check src/app.ts");
+    process.env.INKAN_NO_LISTEN = "1";
+    let mod;
+    try {
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(entry)).href));
+    }
+    catch (err) {
+        if (entry.endsWith(".ts") && err.code === "ERR_UNKNOWN_FILE_EXTENSION") {
+            fail(`Node ${process.versions.node} cannot load .ts files by itself. Use Node 22.18 or newer, or point at the built .js file.`);
+        }
+        throw err;
+    }
+    const app = (mod.default ?? mod.app);
+    if (!app || typeof app.check !== "function")
+        fail(`${entry} has to export the app, as \`export default app\` or \`export const app\`.`);
+    return { app, beforeEach: mod.beforeEach };
+}
+const color = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+switch (command) {
+    case "check": {
+        const only = option("--only");
+        const json = has("--json");
+        const { app, beforeEach } = await load(args[0]);
+        const report = await app.check({ only, beforeEach });
+        if (json)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            console.log(formatReport(report, [app.options.title, app.options.version].filter(Boolean).join(" "), color));
+        process.exit(report.ok ? 0 : 1);
+    }
+    case "openapi": {
+        const out = option("--out", "-o");
+        const { app } = await load(args[0]);
+        const doc = JSON.stringify(app.openapi(), null, 2) + "\n";
+        if (out) {
+            writeFileSync(out, doc);
+            console.log(`  wrote ${out}`);
+        }
+        else
+            process.stdout.write(doc);
+        process.exit(0);
+    }
+    case "routes": {
+        const { app } = await load(args[0]);
+        for (const r of app.routes()) {
+            const n = r.spec.examples?.length ?? 0;
+            const tail = [r.spec.summary, n ? `${n} example${n === 1 ? "" : "s"}` : "no examples"].filter(Boolean).join("  ·  ");
+            console.log(`  ${r.method.padEnd(7)} ${r.path.padEnd(32)} ${tail}`);
+        }
+        process.exit(0);
+    }
+    case "-v":
+    case "--version": {
+        const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        console.log(pkg.version);
+        process.exit(0);
+    }
+    default:
+        console.log(HELP);
+        process.exit(!command || ["help", "--help", "-h"].includes(command) ? 0 : 2);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { inkan, App, Routes, routes, reply, Reply } from "./app.ts";
+export type { AppOptions, Context, Example, Handler, InjectOptions, InjectResponse, LogEntry, Middleware, PathParams, Responses, RouteRecord, RouteSpec, } from "./app.ts";
+export { t, Schema, ValidationError } from "./schema.ts";
+export type { Infer, Issue, JsonSchema, SafeResult } from "./schema.ts";
+export { problem, HttpProblem } from "./problem.ts";
+export type { ProblemBody } from "./problem.ts";
+export { buildOpenAPI } from "./openapi.ts";
+export { formatReport, partialMatch } from "./check.ts";
+export type { CheckOptions, CheckReport, CheckResult } from "./check.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { inkan, App, Routes, routes, reply, Reply } from "./app.js";
+export { t, Schema, ValidationError } from "./schema.js";
+export { problem, HttpProblem } from "./problem.js";
+export { buildOpenAPI } from "./openapi.js";
+export { formatReport, partialMatch } from "./check.js";

package/dist/openapi.d.ts

@@ -0,0 +1,12 @@
+import type { RouteRecord } from "./app.ts";
+export type OpenAPIInfo = {
+    title?: string;
+    version?: string;
+    description?: string;
+    servers?: {
+        url: string;
+        description?: string;
+    }[];
+};
+export declare const toOpenAPIPath: (path: string) => string;
+export declare function buildOpenAPI(records: RouteRecord[], info?: OpenAPIInfo): Record<string, unknown>;

package/dist/openapi.js

@@ -0,0 +1,112 @@
+// Writes an OpenAPI 3.1 document from the routes. Nothing is annotated twice:
+// the schemas that validate a request are the ones that describe it.
+import { STATUS_CODES } from "node:http";
+import { ObjectSchema, t } from "./schema.js";
+export const toOpenAPIPath = (path) => path.replace(/:(\w+)/g, "{$1}").replace(/\*(\w*)$/, (_, n) => `{${n || "rest"}}`);
+const operationId = (r) => r.method.toLowerCase() +
+    r.path
+        .split("/")
+        .filter(Boolean)
+        .map((s) => {
+        const by = s.startsWith(":") || s.startsWith("*");
+        const word = s.replace(/^[:*]/, "").replace(/[^a-zA-Z0-9]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""));
+        return (by ? "By" : "") + word.charAt(0).toUpperCase() + word.slice(1);
+    })
+        .join("");
+function parameters(where, schema, ctx, r) {
+    const out = [];
+    const key = where === "path" ? "params" : where === "header" ? "headers" : "query";
+    if (schema instanceof ObjectSchema) {
+        for (const [name, s] of Object.entries(schema.shape)) {
+            const p = {
+                name,
+                in: where,
+                required: where === "path" || (!s.meta.optional && !s.meta.hasDefault),
+                schema: s._schema(ctx),
+            };
+            if (s.meta.description)
+                p.description = s.meta.description;
+            const examples = (r.spec.examples ?? [])
+                .map((e, i) => [e.name ?? `example${i + 1}`, e[key]?.[name]])
+                .filter(([, v]) => v !== undefined);
+            if (examples.length)
+                p.examples = Object.fromEntries(examples.map(([n, value]) => [n, { value }]));
+            out.push(p);
+        }
+    }
+    else if (where === "path") {
+        for (const m of r.path.matchAll(/[:*](\w*)/g)) {
+            out.push({ name: m[1] || "rest", in: "path", required: true, schema: { type: "string" } });
+        }
+    }
+    return out;
+}
+export function buildOpenAPI(records, info = {}) {
+    const ctx = { components: new Map() };
+    const paths = {};
+    const problemRef = () => t.problem()._schema(ctx);
+    for (const r of records) {
+        const { spec } = r;
+        if (spec.hidden)
+            continue;
+        const op = { operationId: spec.operationId ?? operationId(r) };
+        if (spec.summary)
+            op.summary = spec.summary;
+        if (spec.description)
+            op.description = spec.description;
+        if (spec.tags)
+            op.tags = spec.tags;
+        if (spec.deprecated)
+            op.deprecated = true;
+        const params = [
+            ...parameters("path", spec.params, ctx, r),
+            ...parameters("query", spec.query, ctx, r),
+            ...parameters("header", spec.headers, ctx, r),
+        ];
+        if (params.length)
+            op.parameters = params;
+        if (spec.body) {
+            const examples = (spec.examples ?? []).filter((e) => e.body !== undefined);
+            const media = { schema: spec.body._schema(ctx) };
+            if (examples.length) {
+                media.examples = Object.fromEntries(examples.map((e, i) => [e.name ?? `example${i + 1}`, { value: e.body }]));
+            }
+            op.requestBody = { required: !spec.body.meta.optional, content: { "application/json": media } };
+        }
+        const responses = {};
+        for (const [status, schema] of Object.entries(spec.response ?? {})) {
+            const code = Number(status);
+            const res = { description: schema.meta.description ?? STATUS_CODES[code] ?? "" };
+            if (code !== 204) {
+                res.content = { [code >= 400 ? "application/problem+json" : "application/json"]: { schema: schema._schema(ctx) } };
+            }
+            responses[status] = res;
+        }
+        if ((spec.params || spec.query || spec.headers || spec.body) && !responses["400"]) {
+            responses["400"] = {
+                description: "The input does not match the contract",
+                content: { "application/problem+json": { schema: problemRef() } },
+            };
+        }
+        if (!Object.keys(responses).length)
+            responses["200"] = { description: "OK" };
+        op.responses = responses;
+        if (spec.examples?.length)
+            op["x-inkan-examples"] = spec.examples;
+        (paths[toOpenAPIPath(r.path)] ??= {})[r.method.toLowerCase()] = op;
+    }
+    const doc = {
+        openapi: "3.1.0",
+        info: {
+            title: info.title ?? "API",
+            version: info.version ?? "0.0.0",
+            ...(info.description ? { description: info.description } : {}),
+        },
+    };
+    if (info.servers)
+        doc.servers = info.servers;
+    doc.paths = paths;
+    if (ctx.components.size)
+        doc.components = { schemas: Object.fromEntries(ctx.components) };
+    return doc;
+}

package/dist/pages.d.ts

@@ -0,0 +1,10 @@
+export declare function docsPage(cfg: {
+    title: string;
+    specUrl: string;
+    inspector?: string;
+}): string;
+export declare function inspectorPage(cfg: {
+    title: string;
+    base: string;
+    docs: string;
+}): string;

package/dist/pages.js

@@ -0,0 +1,286 @@
+// The two pages inkan serves itself: the docs and the request inspector.
+// Plain HTML, CSS and JS in one string each. No CDN, nothing to fetch but the
+// app's own JSON, so they work offline and behind any firewall.
+const css = /* css */ `
+:root{--paper:#f6f0e4;--paper-2:#ede3cf;--card:#fbf7ef;--ink:#2b2420;--ink-2:#74675b;--line:#d8c9b0;
+--seal:#c4381f;--seal-soft:#f4d8cc;--ok:#3d7a4b;--warn:#a26d12;--get:#3d7a4b;--post:#2e5e9c;--put:#a26d12;
+--patch:#76509b;--delete:#c4381f;--mono:ui-monospace,"Cascadia Code","JetBrains Mono",Menlo,Consolas,monospace;
+--sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;color-scheme:light}
+@media (prefers-color-scheme:dark){:root:not([data-theme=light]){--paper:#1a1614;--paper-2:#231e1b;--card:#201b18;
+--ink:#ece1cf;--ink-2:#a3958a;--line:#3b332d;--seal:#e65d3e;--seal-soft:#3a2119;--ok:#79c08a;--warn:#e0a84a;
+--get:#79c08a;--post:#7fa8e6;--put:#e0a84a;--patch:#b897e0;--delete:#e65d3e;color-scheme:dark}}
+*{box-sizing:border-box}html,body{margin:0}
+body{background:var(--paper);color:var(--ink);font:15px/1.55 var(--sans);
+background-image:radial-gradient(var(--line) .6px,transparent .6px);background-size:18px 18px}
+a{color:inherit}code,pre,.mono{font-family:var(--mono);font-size:13px}
+.top{display:flex;align-items:center;gap:14px;padding:14px 22px;border-bottom:1px solid var(--line);
+background:var(--paper);position:sticky;top:0;z-index:5;flex-wrap:wrap}
+.stamp{display:inline-grid;place-items:center;width:30px;height:30px;border:2px solid var(--seal);color:var(--seal);
+border-radius:6px;font-weight:700;transform:rotate(-4deg);font-size:15px;line-height:1}
+.top h1{font:600 16px var(--mono);margin:0}.top .ver{color:var(--ink-2);font:13px var(--mono)}
+.top nav{margin-left:auto;display:flex;gap:6px;flex-wrap:wrap}
+.btn{font:12px var(--mono);border:1px solid var(--ink);background:var(--card);color:var(--ink);padding:5px 10px;
+border-radius:3px;cursor:pointer;text-decoration:none;box-shadow:2px 2px 0 var(--line)}
+.btn:hover{background:var(--paper-2)}.btn:active{transform:translate(1px,1px);box-shadow:1px 1px 0 var(--line)}
+.btn.seal{border-color:var(--seal);color:var(--seal)}
+.layout{display:grid;grid-template-columns:260px minmax(0,1fr);gap:26px;max-width:1180px;margin:0 auto;padding:24px 22px 80px}
+aside{position:sticky;top:76px;align-self:start;max-height:calc(100vh - 96px);overflow:auto}
+aside h4{font:600 11px var(--mono);text-transform:uppercase;letter-spacing:.08em;color:var(--ink-2);margin:18px 0 6px}
+aside a{display:flex;gap:8px;align-items:baseline;padding:3px 6px;border-radius:3px;text-decoration:none;font:12.5px var(--mono)}
+aside a:hover{background:var(--paper-2)}aside a .p{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.m{font:700 10.5px var(--mono);min-width:44px;display:inline-block}
+.m-get{color:var(--get)}.m-post{color:var(--post)}.m-put{color:var(--put)}.m-patch{color:var(--patch)}.m-delete{color:var(--delete)}
+.intro{margin:0 0 22px;color:var(--ink-2);max-width:68ch}
+.win{background:var(--card);border:1px solid var(--ink);border-radius:4px;box-shadow:4px 4px 0 var(--line);margin:0 0 26px;scroll-margin-top:84px}
+.bar{display:flex;align-items:center;gap:10px;padding:8px 12px;border-bottom:1px solid var(--ink);background:var(--paper-2);border-radius:4px 4px 0 0}
+.bar code{font-size:14px;font-weight:600;word-break:break-all}.bar .dep{color:var(--warn);font:11px var(--mono)}
+.bar .sealmark{margin-left:auto;opacity:0;transition:opacity .3s,transform .3s;transform:scale(1.6) rotate(-12deg)}
+.win.sealed .sealmark{opacity:1;transform:scale(1) rotate(-4deg)}
+.win.broken .bar{background:var(--seal-soft)}
+.pad{padding:14px 16px}.sum{margin:0 0 4px;font-weight:600}.desc{margin:0 0 8px;color:var(--ink-2)}
+h5{font:600 11px var(--mono);text-transform:uppercase;letter-spacing:.08em;color:var(--ink-2);margin:16px 0 6px}
+table{border-collapse:collapse;width:100%;font-size:13.5px}
+td,th{text-align:left;padding:5px 8px;border-bottom:1px dashed var(--line);vertical-align:top}
+th{font:600 11px var(--mono);color:var(--ink-2)}
+pre.type{margin:0;padding:10px 12px;background:var(--paper);border:1px solid var(--line);border-radius:3px;overflow:auto;white-space:pre}
+.k{color:var(--ink)}.ty{color:var(--post)}.lit{color:var(--ok)}.cm{color:var(--ink-2)}.ty-ref{color:var(--patch);font-weight:600}
+.status{font:600 12px var(--mono);display:inline-block;min-width:34px}
+.s2{color:var(--ok)}.s3{color:var(--post)}.s4{color:var(--warn)}.s5{color:var(--seal)}
+.ex{border:1px dashed var(--line);border-radius:3px;margin:8px 0;padding:8px 10px}
+.ex-head{display:flex;gap:10px;align-items:center;flex-wrap:wrap}.ex-head .name{font-weight:600}
+.ex-head .req{color:var(--ink-2);font:12px var(--mono);word-break:break-all}.ex-head .btn{margin-left:auto}
+.ex pre{margin:8px 0 0;max-height:280px;overflow:auto;padding:8px 10px;background:var(--paper);border-radius:3px}
+.verdict{font:600 12px var(--mono)}.verdict.ok{color:var(--ok)}.verdict.no{color:var(--seal)}
+.muted{color:var(--ink-2)}.empty{padding:40px;text-align:center;color:var(--ink-2)}
+input.filter{font:13px var(--mono);padding:6px 10px;border:1px solid var(--ink);border-radius:3px;background:var(--card);color:var(--ink);width:260px;max-width:100%}
+.log td{font:12.5px var(--mono);white-space:nowrap}.log tr.row{cursor:pointer}.log tr.row:hover td{background:var(--paper-2)}
+.log td.path{white-space:normal;word-break:break-all}.note{color:var(--seal)}
+.log tr.detail td{white-space:normal;background:var(--paper)}.log tr.detail pre{white-space:pre-wrap;word-break:break-all;margin:4px 0 10px}
+@media (max-width:820px){.layout{grid-template-columns:minmax(0,1fr);padding:16px}aside{position:static;max-height:none}.top{padding:12px 16px}.top nav{margin-left:0}}
+`;
+const esc = /* js */ `
+function esc(s){return String(s).replace(/[&<>"']/g,function(c){return{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[c]})}
+`;
+const page = (title, cfg, body, script) => `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${title.replace(/[<>&"]/g, "")}</title>
+<link rel="icon" href="data:image/svg+xml,${encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect x="3" y="3" width="26" height="26" rx="6" fill="#c4381f"/><rect x="7" y="7" width="18" height="18" rx="3" fill="none" stroke="#fbf7ef" stroke-width="2"/><path d="M12 16.5l3 3 5.5-6.5" fill="none" stroke="#fbf7ef" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg>')}">
+<style>${css}</style></head><body>${body}
+<script>var CFG=${JSON.stringify(cfg).replace(/</g, "\\u003c")};${esc}${script}</script></body></html>`;
+// ---------- docs ----------
+const docsScript = /* js */ `
+var COMP = {};
+var $ = function (s) { return document.querySelector(s); };
+function lit(s) { return '<span class="lit">' + esc(s) + "</span>"; }
+function ty(s) { return '<span class="ty">' + esc(s) + "</span>"; }
+function note(s) {
+  var n = [];
+  if (s.format) n.push(s.format);
+  if (s.minimum !== undefined || s.maximum !== undefined) n.push((s.minimum !== undefined ? s.minimum : "") + ".." + (s.maximum !== undefined ? s.maximum : ""));
+  if (s.minLength !== undefined || s.maxLength !== undefined) n.push("length " + (s.minLength || 0) + ".." + (s.maxLength !== undefined ? s.maxLength : ""));
+  if (s.pattern) n.push("/" + s.pattern + "/");
+  if (s.default !== undefined) n.push("default " + JSON.stringify(s.default));
+  if (s.description) n.push(s.description);
+  return n;
+}
+function render(s, pad) {
+  pad = pad || "";
+  if (!s || !Object.keys(s).length) return ty("any");
+  if (s.$ref) { var name = s.$ref.split("/").pop(); return '<a class="ty-ref" href="#schema-' + esc(name) + '">' + esc(name) + "</a>"; }
+  if (s.anyOf) return s.anyOf.map(function (x) { return render(x, pad); }).join(" | ");
+  if (s.const !== undefined) return lit(JSON.stringify(s.const));
+  if (s.enum) return s.enum.map(function (v) { return lit(JSON.stringify(v)); }).join(" | ");
+  if (s.type === "null") return ty("null");
+  if (s.type === "array") { var inner = render(s.items, pad); return (/ \\| /.test(inner) ? "(" + inner + ")" : inner) + ty("[]"); }
+  if (s.type === "object") {
+    if (!s.properties) return s.additionalProperties ? ty("Record<string, ") + render(s.additionalProperties, pad) + ty(">") : ty("object");
+    var req = s.required || [], keys = Object.keys(s.properties);
+    if (!keys.length) return ty("{}");
+    var lines = keys.map(function (k) {
+      var p = s.properties[k], n = note(p);
+      return pad + "  " + '<span class="k">' + esc(k) + (req.indexOf(k) < 0 ? "?" : "") + "</span>: " + render(p, pad + "  ") +
+        (n.length ? '  <span class="cm">// ' + esc(n.join(", ")) + "</span>" : "");
+    });
+    return "{\\n" + lines.join("\\n") + "\\n" + pad + "}";
+  }
+  return ty(s.type === "integer" ? "int" : s.type || "any");
+}
+function block(schema) { return '<pre class="type">' + render(schema, "") + "</pre>"; }
+function firstContent(c) { if (!c) return null; var k = Object.keys(c)[0]; return k ? c[k].schema : null; }
+function expected(op, ex) {
+  if (ex.status !== undefined) return ex.status;
+  var ok = Object.keys(op.responses || {}).map(Number).filter(function (s) { return s >= 200 && s < 300; }).sort();
+  return ok[0];
+}
+function urlFor(path, ex) {
+  var u = path.replace(/\\{(\\w+)\\}/g, function (_, n) {
+    var v = (ex.params || {})[n]; return v === undefined ? "{" + n + "}" : encodeURIComponent(String(v));
+  });
+  var q = new URLSearchParams();
+  Object.keys(ex.query || {}).forEach(function (k) { [].concat(ex.query[k]).forEach(function (v) { q.append(k, String(v)); }); });
+  var qs = q.toString();
+  return u + (qs ? "?" + qs : "");
+}
+var ROUTES = [];
+function card(path, method, op, idx) {
+  var id = "op-" + (op.operationId || idx);
+  var h = '<section class="win" id="' + esc(id) + '"><header class="bar"><span class="m m-' + method + '">' + method.toUpperCase() +
+    "</span><code>" + esc(path) + "</code>" + (op.deprecated ? '<span class="dep">deprecated</span>' : "") +
+    '<span class="stamp sealmark" title="every example answered as promised">印</span></header><div class="pad">';
+  if (op.summary) h += '<p class="sum">' + esc(op.summary) + "</p>";
+  if (op.description) h += '<p class="desc">' + esc(op.description) + "</p>";
+  if (op.parameters && op.parameters.length) {
+    h += "<h5>parameters</h5><table><tr><th>name</th><th>in</th><th>type</th><th></th></tr>";
+    op.parameters.forEach(function (p) {
+      h += "<tr><td><code>" + esc(p.name) + (p.required ? "" : "?") + "</code></td><td class=muted>" + esc(p.in) +
+        "</td><td><code>" + render(p.schema, "") + "</code></td><td class=muted>" + esc(note(p.schema || {}).concat(p.description || []).join(", ")) + "</td></tr>";
+    });
+    h += "</table>";
+  }
+  if (op.requestBody) h += "<h5>body</h5>" + block(firstContent(op.requestBody.content));
+  h += "<h5>responses</h5><table>";
+  Object.keys(op.responses || {}).forEach(function (s) {
+    var r = op.responses[s], sc = firstContent(r.content);
+    h += '<tr><td style="width:60px"><span class="status s' + s[0] + '">' + esc(s) + "</span></td><td>" + esc(r.description || "") +
+      (sc ? '<pre class="type" style="margin-top:6px">' + render(sc, "") + "</pre>" : "") + "</td></tr>";
+  });
+  h += "</table>";
+  var exs = op["x-inkan-examples"] || [];
+  if (exs.length) {
+    h += "<h5>examples · each one is also a test</h5>";
+    exs.forEach(function (ex, i) {
+      var want = expected(op, ex);
+      ROUTES.push({ id: id, path: path, method: method, op: op, ex: ex, el: id + "-ex" + i });
+      h += '<div class="ex" id="' + id + "-ex" + i + '"><div class="ex-head"><span class="name">' + esc(ex.name || "example " + (i + 1)) +
+        '</span><span class="req">' + method.toUpperCase() + " " + esc(urlFor(path, ex)) + (want ? " → " + want : "") +
+        '</span><button class="btn" data-run="' + (ROUTES.length - 1) + '">send</button></div>' +
+        (ex.body !== undefined ? "<pre>" + esc(JSON.stringify(ex.body, null, 2)) + "</pre>" : "") + '<div class="out"></div></div>';
+    });
+  }
+  return h + "</div></section>";
+}
+function send(i) {
+  var r = ROUTES[i], ex = r.ex, el = document.getElementById(r.el), out = el.querySelector(".out");
+  var headers = Object.assign({}, ex.headers || {}), init = { method: r.method.toUpperCase(), headers: headers };
+  if (ex.body !== undefined) { headers["content-type"] = "application/json"; init.body = JSON.stringify(ex.body); }
+  var t0 = performance.now();
+  out.innerHTML = '<p class="muted mono">sending…</p>';
+  return fetch(urlFor(r.path, ex), init).then(function (res) {
+    return res.text().then(function (text) {
+      var ms = Math.round(performance.now() - t0), want = expected(r.op, ex);
+      var ok = want === undefined ? res.status < 300 : res.status === want, pretty = text;
+      try { pretty = JSON.stringify(JSON.parse(text), null, 2); } catch (e) {}
+      out.innerHTML = '<p class="mono" style="margin:8px 0 0"><span class="status s' + String(res.status)[0] + '">' + res.status +
+        '</span> <span class="muted">' + ms + 'ms</span> <span class="verdict ' + (ok ? "ok" : "no") + '">' +
+        (ok ? "✓ as promised" : "✗ expected " + (want || "a 2xx")) + "</span></p>" + (pretty ? "<pre>" + esc(pretty) + "</pre>" : "");
+      el.dataset.ok = ok ? "1" : "0";
+      stampCard(r.id);
+      return ok;
+    });
+  }).catch(function (e) { out.innerHTML = '<p class="verdict no">' + esc(e.message) + "</p>"; el.dataset.ok = "0"; stampCard(r.id); });
+}
+function stampCard(id) {
+  var win = document.getElementById(id), all = win.querySelectorAll(".ex"), done = 0, good = 0;
+  all.forEach(function (e) { if (e.dataset.ok) { done++; if (e.dataset.ok === "1") good++; } });
+  win.classList.toggle("sealed", done === all.length && good === all.length);
+  win.classList.toggle("broken", done > good);
+}
+function sendAll() {
+  var chain = Promise.resolve();
+  ROUTES.forEach(function (_, i) { chain = chain.then(function () { return send(i); }); });
+}
+function boot(spec) {
+  COMP = (spec.components || {}).schemas || {};
+  document.title = (spec.info.title || "API") + " · docs";
+  $("#title").textContent = spec.info.title || "API";
+  $("#ver").textContent = spec.info.version || "";
+  if (spec.info.description) $("#intro").textContent = spec.info.description;
+  var groups = {}, cards = [], idx = 0;
+  Object.keys(spec.paths).forEach(function (path) {
+    Object.keys(spec.paths[path]).forEach(function (method) {
+      var op = spec.paths[path][method], tag = (op.tags && op.tags[0]) || "routes";
+      (groups[tag] = groups[tag] || []).push({ path: path, method: method, op: op, idx: idx });
+      cards.push(card(path, method, op, idx++));
+    });
+  });
+  var nav = "";
+  Object.keys(groups).forEach(function (g) {
+    nav += "<h4>" + esc(g) + "</h4>";
+    groups[g].forEach(function (r) {
+      nav += '<a href="#op-' + esc(r.op.operationId || r.idx) + '"><span class="m m-' + r.method + '">' + r.method.toUpperCase() +
+        '</span><span class="p">' + esc(r.path) + "</span></a>";
+    });
+  });
+  var names = Object.keys(COMP);
+  if (names.length) {
+    nav += "<h4>schemas</h4>" + names.map(function (n) { return '<a href="#schema-' + esc(n) + '"><span class="p">' + esc(n) + "</span></a>"; }).join("");
+    cards.push(names.map(function (n) {
+      return '<section class="win" id="schema-' + esc(n) + '"><header class="bar"><code>' + esc(n) + '</code></header><div class="pad">' + block(COMP[n]) + "</div></section>";
+    }).join(""));
+  }
+  $("#nav").innerHTML = nav;
+  $("#main").innerHTML = cards.join("") || '<p class="empty">No routes yet.</p>';
+  document.addEventListener("click", function (e) { var b = e.target.closest("[data-run]"); if (b) send(Number(b.dataset.run)); });
+  if (!ROUTES.length) $("#all").remove();
+}
+$("#all").addEventListener("click", sendAll);
+if (CFG.spec) fetch(CFG.spec).then(function (r) { return r.json(); }).then(boot);
+else $("#main").innerHTML = '<p class="empty">The OpenAPI document is switched off.</p>';
+`;
+export function docsPage(cfg) {
+    const body = `
+<header class="top"><span class="stamp">印</span><h1 id="title">${cfg.title.replace(/[<>&]/g, "")}</h1><span class="ver" id="ver"></span>
+<nav><button class="btn seal" id="all" title="Sends every example. Examples that change data change it for real.">▶ send every example</button>
+${cfg.specUrl ? `<a class="btn" href="${cfg.specUrl}">openapi.json</a>` : ""}
+${cfg.inspector ? `<a class="btn" href="${cfg.inspector}">inspector</a>` : ""}</nav></header>
+<div class="layout"><aside id="nav"></aside><main><p class="intro" id="intro">Every route below carries its contract. The examples are the same ones <code>inkan check</code> runs, so what you read here is what the server was tested to do.</p><div id="main"><p class="empty">loading…</p></div></main></div>`;
+    return page(cfg.title + " · docs", { spec: cfg.specUrl }, body, docsScript);
+}
+// ---------- inspector ----------
+const inspectorScript = /* js */ `
+var since = 0, paused = false, rows = [], open = {};
+var $ = function (s) { return document.querySelector(s); };
+function line(e) {
+  var t = e.at.slice(11, 19);
+  return '<tr class="row" data-id="' + e.id + '"><td class="muted">' + t + '</td><td><span class="m m-' + e.method.toLowerCase() + '">' + esc(e.method) +
+    '</span></td><td class="path">' + esc(e.path) + '</td><td><span class="status s' + String(e.status)[0] + '">' + e.status +
+    '</span></td><td class="muted">' + e.ms + "ms</td><td class=muted>" + esc(e.route || "—") + '</td><td class="note">' + esc(e.notes.join("; ")) + "</td></tr>" +
+    (open[e.id] ? '<tr class="detail"><td colspan="7">' + detail(e) + "</td></tr>" : "");
+}
+function pretty(s) { if (s === undefined) return "—"; try { return JSON.stringify(JSON.parse(s), null, 2); } catch (x) { return s; } }
+function detail(e) {
+  return '<h5>request headers</h5><pre>' + esc(Object.keys(e.request.headers).map(function (k) { return k + ": " + e.request.headers[k]; }).join("\\n")) +
+    '</pre><h5>request body</h5><pre>' + esc(pretty(e.request.body)) + '</pre><h5>response body</h5><pre>' + esc(pretty(e.response.body)) + "</pre>";
+}
+function draw() {
+  var f = $("#filter").value.toLowerCase();
+  var shown = rows.filter(function (e) { return !f || (e.method + " " + e.path + " " + e.status + " " + e.notes.join(" ")).toLowerCase().indexOf(f) >= 0; });
+  $("#body").innerHTML = shown.length ? shown.map(line).join("") : '<tr><td colspan="7" class="empty">Nothing yet. Send a request and it shows up here.</td></tr>';
+  $("#count").textContent = rows.length + " request" + (rows.length === 1 ? "" : "s");
+}
+function poll() {
+  if (paused) return;
+  fetch(CFG.base + "/log.json?since=" + since).then(function (r) { return r.json(); }).then(function (list) {
+    if (!list.length) return;
+    since = list[list.length - 1].id;
+    rows = list.reverse().concat(rows).slice(0, 200);
+    draw();
+  }).catch(function () {});
+}
+$("#body").addEventListener("click", function (e) { var tr = e.target.closest("tr.row"); if (!tr) return; var id = tr.dataset.id; open[id] = !open[id]; draw(); });
+$("#filter").addEventListener("input", draw);
+$("#pause").addEventListener("click", function () { paused = !paused; this.textContent = paused ? "▶ resume" : "❚❚ pause"; });
+$("#clear").addEventListener("click", function () { rows = []; open = {}; draw(); });
+draw(); poll(); setInterval(poll, 1000);
+`;
+export function inspectorPage(cfg) {
+    const body = `
+<header class="top"><span class="stamp">印</span><h1>${cfg.title.replace(/[<>&]/g, "")}</h1><span class="ver">inspector · only on this machine</span>
+<nav><input class="filter" id="filter" placeholder="filter: path, status, note…">
+<button class="btn" id="pause">❚❚ pause</button><button class="btn" id="clear">clear</button>
+${cfg.docs ? `<a class="btn" href="${cfg.docs}">docs</a>` : ""}</nav></header>
+<div style="max-width:1180px;margin:0 auto;padding:22px">
+<p class="intro">The last 200 requests, newest first. A red note means a request or an answer broke the contract. Secret headers show as •••. <span id="count" class="mono"></span></p>
+<section class="win"><div class="pad" style="overflow:auto"><table class="log"><thead><tr><th>time</th><th>method</th><th>path</th><th>status</th><th>took</th><th>route</th><th>notes</th></tr></thead><tbody id="body"></tbody></table></div></section></div>`;
+    return page(cfg.title + " · inspector", { base: cfg.base }, body, inspectorScript);
+}

package/dist/problem.d.ts

@@ -0,0 +1,26 @@
+import type { Issue } from "./schema.ts";
+export type ProblemBody = {
+    type: string;
+    title: string;
+    status: number;
+    detail?: string;
+    instance?: string;
+    [extra: string]: unknown;
+};
+export declare class HttpProblem extends Error {
+    status: number;
+    type: string;
+    title: string;
+    detail?: string;
+    extra: Record<string, unknown>;
+    headers: Record<string, string>;
+    constructor(status: number, type: string, detail?: string, extra?: Record<string, unknown>, headers?: Record<string, string>);
+    toJSON(): ProblemBody;
+}
+/**
+ * Stops the handler with an error response.
+ *
+ *   throw problem(404, "user-not-found", `No user with id ${id}`)
+ */
+export declare function problem(status: number, type: string, detail?: string, extra?: Record<string, unknown>): HttpProblem;
+export declare const validationProblem: (where: string, issues: Issue[]) => HttpProblem;

package/dist/problem.js

@@ -0,0 +1,38 @@
+// Errors as RFC 9457 problem documents: every failure has the same shape,
+// a stable `type` code to switch on, and a human `detail`.
+import { STATUS_CODES } from "node:http";
+export class HttpProblem extends Error {
+    status;
+    type;
+    title;
+    detail;
+    extra;
+    headers;
+    constructor(status, type, detail, extra = {}, headers = {}) {
+        super(detail ?? type);
+        this.name = "HttpProblem";
+        this.status = status;
+        this.type = type;
+        this.title = STATUS_CODES[status] ?? "Error";
+        this.detail = detail;
+        this.extra = extra;
+        this.headers = headers;
+    }
+    toJSON() {
+        const body = { type: this.type, title: this.title, status: this.status };
+        if (this.detail)
+            body.detail = this.detail;
+        return { ...body, ...this.extra };
+    }
+}
+/**
+ * Stops the handler with an error response.
+ *
+ *   throw problem(404, "user-not-found", `No user with id ${id}`)
+ */
+export function problem(status, type, detail, extra) {
+    return new HttpProblem(status, type, detail, extra);
+}
+export const validationProblem = (where, issues) => new HttpProblem(400, "validation", `The ${where} does not match the contract`, {
+    errors: issues.map((i) => ({ in: where, path: i.path, message: i.message })),
+});

package/dist/router.d.ts

@@ -0,0 +1,18 @@
+export type Match<R> = {
+    kind: "found";
+    route: R;
+    params: Record<string, string>;
+} | {
+    kind: "method";
+    allow: string[];
+} | {
+    kind: "none";
+};
+export declare function splitPath(path: string): string[];
+export declare class Router<R> {
+    private root;
+    add(method: string, path: string, route: R): void;
+    private put;
+    match(method: string, path: string): Match<R>;
+    private walk;
+}